Update docs

bioteam · May 28, 2024 · 60b92fe · 60b92fe
1 parent f9ac059
commit 60b92fe
Show file tree

Hide file tree

Showing 10 changed files with 82 additions and 12 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,6 @@
 _build
 .venv
+.DS_Store
+*.egg-info
 sphinx_venv
 *.pyc
diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/conf.py b/docs/conf.py
@@ -29,6 +29,7 @@
     "sphinx.ext.githubpages", # used for hosting on GitHub Pages
     "sphinx.ext.todo",
     "autoapi.extension",
+    "sphinx.ext.autosectionlabel",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx_copybutton", # adds a copy button to source code blocks

diff --git a/docs/guides/.DS_Store b/docs/guides/.DS_Store
diff --git a/docs/guides/guide_installation.rst b/docs/guides/guide_installation.rst
@@ -19,25 +19,47 @@ Clone the `sphinx-documentation-demo <https://github.com/bioteam/sphinx-document
 
 2. Installing Sphinx 
 ---------------------------------
-Sphinx, and extensions for Sphinx, are *python packages* that can be installed on your computer.
-The packages you need to install are in :code:`requirements.txt` in the :code:`sphinx-documentation-demo` repository.
+Sphinx and its extensions are *python packages* that can be installed.
+The packages you need to install are in :code:`pyproject.toml` located in the :code:`sphinx-documentation-demo` repository.
 It's a good idea to install them in a **virtual environment**.
 
 
 
-2a. Using :code:`venv` to install
+2a. Using :code:`install.sh` to install
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The :code:`install.sh` script can be used to create a new python environment and install the scripts needed for Sphinx to function.
+While in the :code:`sphinx-documentation-demo` directory, run:
 
 .. code-block:: bash
 
-    python -m venv sphinx_venv
-    source sphinx_venv/bin/activate
-    pip install -r requirements.txt
+    bash install.sh
 
+This will create a **hidden** environment folder :code:`.env` and install the packages located in :code:`pyproject.toml`.
 
+2b. Activating environment using :code:`source.sh`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+After using :code:`install.sh`, or **whenever you open a new command terminal**, make sure that you **activate** the environment by running the following command while in the :code:`sphinx-documentation-demo` directory:
+.. _My target:
 
-3. Building Documentation
--------------------------
+.. code-block:: bash
+
+    source source.sh
+
+If successful, you should have :code:`(.env)` inserted at the beginning of your command prompt.
+
+
+3. Building Documentation on your Laptop
+----------------------------------------
+The :code:`docs/` folder in the :code:`sphinx-documentation-demo` project contains the .rst files that we will compile into a static webpage.
+You can either run :code:`sphinx-build` (see section 3a) or :code:`sphinx-autobuild` (see section 3b).
+
+.. warning::
+
+    Make sure you have activated your python virtual environment before using either option.
+    See :ref:`2b. Activating environment using :code:`source.sh``
+
+3a. Using :code:`sphinx-build`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The documentation for the :code:`sphinx-documentation-demo` is located in :code:`docs/`.
 While in the root project directory, do:
 
@@ -50,8 +72,11 @@ You can open the file :code:`docs/index.html` on your computer to view the HTML
 
 
 
-3a. Using :code:`sphinx-autobuild`
+3b. Using :code:`sphinx-autobuild`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. tip::
+
+    This option is probably the one you want.
 The :code:`sphinx-autobuild` extension allows us to build local documentation whenever we make changes.
 It also refreshes the web browser so you can see the changes "live". This makes it **very convenient for rapid development**.
 
@@ -65,7 +90,49 @@ 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.
 
-.. todo::
+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`
 
-    Finish the guide for remote building on GitHub.
diff --git a/docs/guides/images/.DS_Store b/docs/guides/images/.DS_Store
diff --git a/docs/guides/images/guide_install_page_branch.png b/docs/guides/images/guide_install_page_branch.png
diff --git a/docs/guides/images/guide_install_repo_page_tab.png b/docs/guides/images/guide_install_repo_page_tab.png
diff --git a/docs/guides/images/guide_install_repo_settings.png b/docs/guides/images/guide_install_repo_settings.png
diff --git a/docs/guides/layout/layout_basic.rst b/docs/guides/layout/layout_basic.rst
@@ -101,7 +101,7 @@ The left navigation bar allows users to navigate between documents that have bee
 Each tab will have its own left navigation bar, allowing you to organize :term:`rST` files into one "folder" per tab.
 
 Right Navigation Bar
-===================
+=====================
 .. figure:: images/layout_right.png
         :class: sd-border-2