Update docs

docs/guides/guide_installation.rst

@@ -1,12 +1,11 @@
 Installing Sphinx
 =================
+This guide will cover how to install Sphinx **locally** on your laptop. 
+When you need to write a lot of documentation, it's a **good idea** to do it all locally.
+We will go over:
 
-
-Local Installation
-==================
-
-.. tip::
-    When you need to write a lot of documentation, it's a **good idea to do it all locally.** 
+1. Installing Sphinx using a virtual environment
+2. How to build documentation locally using Sphinx
 
 
 1. Cloning the Repo
@@ -87,123 +86,4 @@ While in the virtual environment, run the following command:
 
     sphinx-autobuild docs _build
 
-You can then point your web browser to: http://127.0.0.1:8000/
-
-Remote Build on GitHub
-======================
-The :code:`_build` directory **should not be pushed to GitHub**. 
-Instead we will use a GitHub Workflow to automatically build documentation that is pushed to the repository.
-The built documentation will then be automatically served up on a webpage in :code:`GitHub Pages`
-
-1. Set up GitHub Pages
-----------------------
-GitHub Pages allow users to view web pages generated by our documentation. 
-While there already a page set up for the :code`sphinx-documentation-demo` project, you will need to do the following steps for a new project:
-
-1a. Navigate to Page settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. figure:: images/guide_install_repo_settings.png
-    :class: sd-border-2
-
-    Click the Settings tab in the project you want to add to GitHub Pages.
-
-
-.. figure:: images/guide_install_repo_page_tab.png
-    :class: sd-border-2
-
-    Click the Pages tab (in the left sidebar) in the Settings page.
-
-
-1b. Select branch to use with GitHub Pages 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. warning::
-
-    The GitHub repo must be **public** in order for it to be accessible via GitHub Pages.
-
-.. figure:: images/guide_install_page_branch.png
-    :class: sd-border-2
-
-    When documentation is successfully deployed, you will see a link that looks like :code:`A`. For a new repo, this will not be active.
-    You will need to set the branch (see :code:`B`). 
-    This demo uses a separate branch called :code:`gh-pages` to deploy documentation. 
-
-2. Using GitHub Workflow to Build Documentation
------------------------------------------------
-GitHub can automatically discover workflows located in the :code:`.github/workflows` directory within the project directory.
-We will be using a workflow to build documentation whenever a **new commit is pushed to the repository**.
-
-2a. Example Workflow
-~~~~~~~~~~~~~~~~~~~~
-We will be reviewing the workflow that :code:`sphinx-documentation-demo` uses.
-
-You can find the workflow in :code:`sphinx-documentation-demo/.github/workflows/documentation.yml`
-
-.. code-block:: 
-    :emphasize-lines: 16,19,24,26
-    :linenos:
-
-    name: documentation
-
-    on: [push, pull_request, workflow_dispatch]
-
-    permissions:
-    contents: write
-
-    jobs:
-    docs:
-        runs-on: ubuntu-latest
-        steps:
-        - uses: actions/checkout@v3
-        - uses: actions/setup-python@v3
-        - name: Install dependencies
-            run: |
-            pip install sphinx pydata-sphinx-theme sphinx-design sphinx-copybutton sphinx-autoapi
-        - name: Sphinx build
-            run: |
-            sphinx-build docs _build
-        - name: Deploy to GitHub Pages
-            uses: peaceiris/actions-gh-pages@v3
-            if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-            with:
-            publish_branch: gh-pages
-            github_token: ${{ secrets.GITHUB_TOKEN }}
-            publish_dir: _build/
-            force_orphan: true
-
-
-* **Line 16.** Install dependencies
-   * This tells GitHub to install sphinx and its dependencies to the ubuntu image. 
-   * **Note**: After you add a new sphinx extension to :code:`pyproject.toml` and to :code:`docs/conf.py`, you'll also need to add the dependency to the list on line 16.
-* **Line 19.** Build Docs
-   * This runs :code:`sphinx-build` on the :code:`docs/` directory (in the repo) and creates the :code:`_build/` directory.
-* Line 24. Publish to branch 
-   * After building the docs, this line tells GitHub to publish the changes to the :code:`gh-pages` branch.
-   * **Note**: this needs to be the same branch that GitHub Pages is set to publish with.
-* **Line 26.** Specify directory to publish
-   * This informs GitHub Pages where the static HTML documentation (built by :code:`sphinx-build`) is located.
-
-
-3. Verifying GitHub Workflow Actions
-------------------------------------
-Using the previously mentioned workflow, a GitHub Action will be triggered whenever a commit is pushed to the repo.
-You can monitor running jobs from your GitHub Repository. 
-
-.. figure:: images/guide_install_github_actions_tab.png
-    :class: sd-border-2
-
-    Click on the :code:`Actions` tab.
-
-.. figure:: images/guide_install_actions_build.png
-    :class: sd-border-2
-
-    Current and previous workflow runs are listed in the Actions tab.
-    The color of the icon indicates the current status of the run.
-    You may notice a :code:`pages build and deployment` job running. This is reponsible for building the docs.
-
-.. figure:: images/guide_install_actions_error.png
-    :class: sd-border-2
-
-    A red icon indicates that the run has failed. You can click on a run to get debug info for each step.
-    Featured in this figure is a very common error: sphinx is missing an extension because it was not installed in the :code:`documentation.yml` workflow.
-
-    To fix this, :code:`sphinx-copybutton` had to be added to line 16 in :code:`documentation.yml` (see :ref:`2a. Example Workflow`)
+You can then point your web browser to: http://127.0.0.1:8000/

docs/guides/guide_remote.rst

@@ -0,0 +1,122 @@
+Hosting Sphinx on GitHub Pages
+==============================
+
+While you can install Sphinx on your laptop and build documentation locally, ultimately you will want to share docs via a web server.
+To do this, we will go over:
+
+
+1. Setting up GitHub pages for a repository
+2. Using GitHub Workflows to automate building documentation
+
+1. Set up GitHub Pages
+======================
+GitHub Pages allow users to view web pages generated by our documentation. 
+While there already a page set up for the :code:`sphinx-documentation-demo` project, you will need to do the following steps for a new project:
+
+1a. Navigate to Page settings
+-----------------------------
+.. figure:: images/guide_install_repo_settings.png
+    :class: sd-border-2
+
+    Click the Settings tab in the project you want to add to GitHub Pages.
+
+
+.. figure:: images/guide_install_repo_page_tab.png
+    :class: sd-border-2
+
+    Click the Pages tab (in the left sidebar) in the Settings page.
+
+
+1b. Select branch to use with GitHub Pages 
+------------------------------------------
+.. warning::
+
+    The GitHub repo must be **public** in order for it to be accessible via GitHub Pages.
+
+.. figure:: images/guide_install_page_branch.png
+    :class: sd-border-2
+
+    When documentation is successfully deployed, you will see a link that looks like :code:`A`. For a new repo, this will not be active.
+    You will need to set the branch (see :code:`B`). 
+    This demo uses a separate branch called :code:`gh-pages` to deploy documentation. 
+
+2. Using GitHub Workflow to Build Documentation
+===============================================
+GitHub can automatically discover workflows located in the :code:`.github/workflows` directory within the project directory.
+We will be using a workflow to build documentation whenever a **new commit is pushed to the repository**.
+
+2a. Example Workflow
+--------------------
+We will be reviewing the workflow that :code:`sphinx-documentation-demo` uses.
+
+You can find the workflow in :code:`sphinx-documentation-demo/.github/workflows/documentation.yml`
+
+.. code-block:: 
+    :emphasize-lines: 16,19,24,26
+    :linenos:
+
+    name: documentation
+
+    on: [push, pull_request, workflow_dispatch]
+
+    permissions:
+    contents: write
+
+    jobs:
+    docs:
+        runs-on: ubuntu-latest
+        steps:
+        - uses: actions/checkout@v3
+        - uses: actions/setup-python@v3
+        - name: Install dependencies
+            run: |
+            pip install sphinx pydata-sphinx-theme sphinx-design sphinx-copybutton sphinx-autoapi
+        - name: Sphinx build
+            run: |
+            sphinx-build docs _build
+        - name: Deploy to GitHub Pages
+            uses: peaceiris/actions-gh-pages@v3
+            if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+            with:
+            publish_branch: gh-pages
+            github_token: ${{ secrets.GITHUB_TOKEN }}
+            publish_dir: _build/
+            force_orphan: true
+
+
+* **Line 16.** Install dependencies
+   * This tells GitHub to install sphinx and its dependencies to the ubuntu image. 
+   * **Note**: After you add a new sphinx extension to :code:`pyproject.toml` and to :code:`docs/conf.py`, you'll also need to add the dependency to the list on line 16.
+* **Line 19.** Build Docs
+   * This runs :code:`sphinx-build` on the :code:`docs/` directory (in the repo) and creates the :code:`_build/` directory.
+* Line 24. Publish to branch 
+   * After building the docs, this line tells GitHub to publish the changes to the :code:`gh-pages` branch.
+   * **Note**: this needs to be the same branch that GitHub Pages is set to publish with.
+* **Line 26.** Specify directory to publish
+   * This informs GitHub Pages where the static HTML documentation (built by :code:`sphinx-build`) is located.
+
+
+3. Verifying GitHub Workflow Actions
+====================================
+Using the previously mentioned workflow, a GitHub Action will be triggered whenever a commit is pushed to the repo.
+You can monitor running jobs from your GitHub Repository. 
+
+.. figure:: images/guide_install_github_actions_tab.png
+    :class: sd-border-2
+
+    Click on the :code:`Actions` tab.
+
+.. figure:: images/guide_install_actions_build.png
+    :class: sd-border-2
+
+    Current and previous workflow runs are listed in the Actions tab.
+    The color of the icon indicates the current status of the run.
+    You may notice a :code:`pages build and deployment` job running. This is reponsible for building the docs.
+
+.. figure:: images/guide_install_actions_error.png
+    :class: sd-border-2
+
+    A red icon indicates that the run has failed. You can click on a run to get debug info for each step.
+    Featured in this figure is a very common error: sphinx is missing an extension because it was not installed in the :code:`documentation.yml` workflow.
+
+    To fix this, :code:`sphinx-copybutton` had to be added to line 16 in :code:`documentation.yml` (see :ref:`2a. Example Workflow`)

docs/guides/index.rst

@@ -8,6 +8,7 @@ Guides
 
    guide_what_is_sphinx
    guide_installation
+   guide_remote
 
 .. toctree::
    :maxdepth: 1

docs/guides/walkthrough_adding_new_tab.rst

@@ -64,7 +64,7 @@ The following is a quick sketch of where Sphinx would expect files to be based o
       ┃ ┗ 📜index.rst       ← index for tab "tab_3"
       ┗ 📜index.rst         ← root index
 
-Creating "test" tab folder and empty index
+Creating "test_tab" folder and empty index
 ------------------------------------------
 We will now try to add a new tab to Sphinx.
 It will be called "test_tab" and will be next to the other tabs already in our documentation.
@@ -77,7 +77,7 @@ It will be called "test_tab" and will be next to the other tabs already in our d
 
 1. Create a new empty directory called "test" at: :code:`docs/test_tab/`
 2. Create a new empty "index.rst" file at: :code:`docs/test_tab/index.rst`
-3. Inside :code:`docs/index.rst`, in the indented :code:`toctree`, append the line :code:`test_tab/index`. It should look like the following:
+3. Inside :code:`docs/index.rst`, in the indented :term:`toctree`, append the line :code:`test_tab/index`. It should look like the following:
 
 
 .. code-block::