Merge pull request #18980 from trallard/trallard/docs-patch

DOC: Gitpod documentation enhancements

4 files changed, 78 insertions, 47 deletions

diff --git a/doc/source/dev/development_gitpod.rst b/doc/source/dev/development_gitpod.rst
index 282103cc5..92cca81fc 100644
--- a/doc/source/dev/development_gitpod.rst
+++ b/doc/source/dev/development_gitpod.rst
@@ -35,7 +35,7 @@ Make sure to select **All repositories** access option to avoid issues with
 permissions later on. Click on the green **Install** button
 
 .. image:: ./gitpod-imgs/installing-gitpod-io.png
-    :alt: Gitpod repository access and installation screenshot
+   :alt: Gitpod repository access and installation screenshot
 
 This will install the necessary hooks for the integration.
 
@@ -46,10 +46,8 @@ The best way to work on NumPy as a contributor is by making a fork of the
 repository first.
 
 #. Browse to the `NumPy repository on GitHub`_ and `create your own fork`_.
-
 #. Browse to your fork. Your fork will have a URL like 
-#. https://github.com/melissawm/NumPy, except with your GitHub username in 
-#. place of "melissawm".
+   https://github.com/melissawm/NumPy, except with your GitHub username in place of ``melissawm``.
 
 Starting Gitpod
 ----------------
@@ -59,7 +57,7 @@ which will add a **Gitpod** button next to the **Code** button in the
 repository:
 
 .. image:: ./gitpod-imgs/NumPy-github.png
-    :alt: NumPy repository with Gitpod button screenshot
+   :alt: NumPy repository with Gitpod button screenshot
 
 #. If you install the extension - you can click the **Gitpod** button to start 
    a new workspace.
@@ -78,10 +76,10 @@ repository:
    might be some actions running. This will ensure that you have a development 
    version of NumPy installed and that the docs are being pre-built for you.
 
-#. Once the build is complete, you can :ref:`test the build<testing-builds>` by 
+#. When your workspace is ready, you can :ref:`test the build<testing-builds>` by 
    entering::
 
-        $ python runtests.py -v
+      $ python runtests.py -v
 
 ``runtests.py`` is another script in the NumPy root directory. It runs a suite 
 of tests that make sure NumPy is working as it should, and ``-v`` activates the 
@@ -95,11 +93,11 @@ can check the Getting started `VSCode docs`_ to familiarize yourself with it.
 Your workspace will look similar to the image below:
 
 .. image:: ./gitpod-imgs/gitpod-workspace.png
-    :alt: Gitpod workspace screenshot
+   :alt: Gitpod workspace screenshot
 
 .. note::  By default, VSCode initializes with a light theme. You can change to 
-    a dark theme by with the keyboard shortcut :kbd:`Cmd-K Cmd-T` in Mac or 
-    :kbd:`Ctrl-K Ctrl-T` in Linux and Windows.
+   a dark theme by with the keyboard shortcut :kbd:`Cmd-K Cmd-T` in Mac or 
+   :kbd:`Ctrl-K Ctrl-T` in Linux and Windows.
 
 We have marked some important sections in the editor:
 
@@ -111,7 +109,7 @@ We have marked some important sections in the editor:
 #. GitHub Pull Requests extension - you can use this to work with Pull Requests 
    from your workspace.
 #. Marketplace extensions - we have added some essential extensions to the NumPy 
-#. Gitpod. Still, you can also install other extensions or syntax highlighting 
+   Gitpod. Still, you can also install other extensions or syntax highlighting 
    themes for your user, and these will be preserved for you.
 #. Your workspace directory - by default, it is ``/workspace/numpy``. **Do not 
    change this** as this is the only directory preserved in Gitpod.
@@ -135,15 +133,15 @@ before working on your contributions.
 When using Gitpod, git is pre configured for you:
 
 #. You do not need to configure your git username, and email as this should be 
-#. done for you as you authenticated through GitHub. You can check the git 
-#. configuration with the command ``git config --list`` in your terminal.
+   done for you as you authenticated through GitHub. You can check the git 
+   configuration with the command ``git config --list`` in your terminal.
 #. As you started your workspace from your own NumPy fork, you will by default 
-#. have both "upstream "and "origin "added as remotes. You can verify this by 
-#. typing ``git remote`` on your terminal or by clicking on the **branch name** 
-#. on the status bar (see image below).
+   have both ``upstream`` and ``origin`` added as remotes. You can verify this by 
+   typing ``git remote`` on your terminal or by clicking on the **branch name** 
+   on the status bar (see image below).
 
-.. image:: ./gitpod-imgs/NumPy-gitpod-branches.png
-    :alt: Gitpod workspace branches plugin screenshot
+   .. image:: ./gitpod-imgs/NumPy-gitpod-branches.png
+      :alt: Gitpod workspace branches plugin screenshot
 
 Rendering the NumPy documentation
 ----------------------------------
@@ -190,8 +188,7 @@ uses the rst extension with docutils.
     .. image:: ./gitpod-imgs/vscode-rst.png
         :alt: Gitpod workspace VSCode open rst screenshot
 
-#. As you work on the document, you will see a live rendering of it on the 
-    editor.
+#. As you work on the document, you will see a live rendering of it on the editor.
 
     .. image:: ./gitpod-imgs/rst-rendering.png
         :alt: Gitpod workspace VSCode rst rendering screenshot
@@ -199,40 +196,74 @@ uses the rst extension with docutils.
 If you want to see the final output with the ``html`` theme you will need to 
 rebuild the docs with ``make html`` and use Live Serve as described in option 1.
 
-FAQ's
------
+FAQ's and troubleshooting
+-------------------------
+
+How long is my Gitpod workspace kept for?
+*****************************************
+
+Your stopped workspace will be kept for 14 days and deleted afterwards if you do 
+not use them.
+
+Can I come back to a previous workspace?
+*****************************************
+
+Yes, let's say you stepped away for a while and you want to carry on working on 
+your NumPy contributions. You need to visit https://gitpod.io/workspaces and 
+click on the workspace you want to spin up again. All your changes will be there 
+as you last left them.
+
+Can I install additional VSCode extensions?
+*******************************************
+
+Absolutely! Any extensions you installed will be installed in your own workspace 
+and preserved.
+
+I registered on Gitpod but I still cannot see a ``Gitpod`` button in my repositories.
+*************************************************************************************
+
+Head to https://gitpod.io/integrations and make sure you are logged in. 
+Hover over GitHub and click on the three buttons that appear on the right. 
+Click on edit permissions and make sure you have ``user:email``, 
+``read:user``, and ``public_repo`` checked. Click on **Update Permissions** 
+and confirm the changes in the GitHub application page.
+
+.. image:: ./gitpod-imgs/gitpod-edit-permissions-gh.png
+   :alt: Gitpod integrations - edit GH permissions screenshot
+
+How long does my workspace stay active if I'm not using it?
+***********************************************************
+
+If you keep your workspace open in a browser tab but don't interact with it, 
+it will shut down after 30 minutes. If you close the browser tab, it will 
+shut down after 3 minutes.
 
-#. How long is my Gitpod workspace kept for?
-    Your stopped workspace will be kept for 14 days and deleted afterwards if 
-    you do not use them.
+My terminal is blank - there is no cursor and it's completely unresponsive
+**************************************************************************
 
-#. Can I come back to a previous workspace?
-    Yes, let's say you stepped away for a while and you want to carry on working 
-    on your NumPy contributions. You need to visit https://gitpod.io/workspaces 
-    and click on the workspace you want to spin up again. All your changes will 
-    be there as you last left them.
+Unfortunately this is a known-issue on Gitpod's side. You can sort this 
+issue in two ways:
 
-#. Can I install additional VSCode extensions?
-    Absolutely! Any extensions you installed will be installed in your own 
-    workspace and preserved.
+#. Create a new Gitpod workspace altogether.
+#. Head to your `Gitpod dashboard <https://gitpod.io/workspaces>`_ and locate 
+   the running workspace. Hover on it and click on the **three dots menu** 
+   and then click on **Stop**. When the workspace is completely stopped you 
+   can click on its name to restart it again.   
 
-#. I registered on Gitpod but I still cannot see a ``Gitpod`` button in my 
-   repositories
+.. image:: ./gitpod-imgs/gitpod-dashboard-stop.png
+   :alt: Gitpod dashboard and workspace menu screenshot
 
-    Head to https://gitpod.io/integrations and make sure you are logged in. 
-    Hover over GitHub and click on the three buttons that appear on the right. 
-    Click on edit permissions and make sure you have ``user:email``, 
-    ``read:user``, and ``public_repo`` checked.
-    Click on **Update Permissions** and confirm the changes in the 
-    GitHub application page.
+I authenticated through GitHub but I still cannot commit to the repository through Gitpod. 
+******************************************************************************************
 
-    .. image:: ./gitpod-imgs/gitpod-edit-permissions-gh.png
-        :alt: Gitpod integrations - edit GH permissions screenshot
+Head to https://gitpod.io/integrations and make sure you are logged in. 
+Hover over GitHub and click on the three buttons that appear on the right. 
+Click on edit permissions and make sure you have ``public_repo`` checked.
+Click on **Update Permissions** and confirm the changes in the 
+GitHub application page.
 
-#. How long does my workspace stay active if I'm not using it?
-    If you keep your workspace open in a browser tab but don't interact with it, 
-    it will shut down after 30 minutes. If you close the browser tab, it will 
-    shut down after 3 minutes.
+.. image:: ./gitpod-imgs/gitpod-edit-permissions-repo.png
+   :alt: Gitpod integrations - edit GH repository permissions screenshot
 
 .. _Gitpod: https://www.gitpod.io/
 .. _NumPy repository on GitHub: https://github.com/NumPy/NumPy
diff --git a/doc/source/dev/gitpod-imgs/gitpod-dashboard-stop.png b/doc/source/dev/gitpod-imgs/gitpod-dashboard-stop.png
new file mode 100644
index 000000000..40f137745
--- /dev/null
+++ b/doc/source/dev/gitpod-imgs/gitpod-dashboard-stop.png
diff --git a/doc/source/dev/gitpod-imgs/gitpod-edit-permissions-repo.png b/doc/source/dev/gitpod-imgs/gitpod-edit-permissions-repo.png
new file mode 100644
index 000000000..8bfaff81c
--- /dev/null
+++ b/doc/source/dev/gitpod-imgs/gitpod-edit-permissions-repo.png
diff --git a/doc/source/dev/gitpod-imgs/gitpod-workspace.png b/doc/source/dev/gitpod-imgs/gitpod-workspace.png
index 618b7063b..a65c9bd7e 100644
--- a/doc/source/dev/gitpod-imgs/gitpod-workspace.png
+++ b/doc/source/dev/gitpod-imgs/gitpod-workspace.png