Update guides

Author: jramsdell-bt

docs/.DS_Store

@@ -33,3 +33,8 @@ html[data-theme="light"] {
 html[data-theme="dark"] {
     --pst-color-primary: rgb(0, 174, 255);
 }
+
+/* The default font size is fairly small, so this increases it */
+body {
+    font-size: 1.3em
+}

docs/_static/css/custom.css

@@ -31,8 +31,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    # githubpages just adds a .nojekyll file
-    "sphinx.ext.githubpages",
+    "sphinx.ext.githubpages", # used for hosting on GitHub Pages
+    "sphinx.ext.todo",
+    "sphinx_copybutton", # adds a copy button to source code blocks
     "sphinx_design"
 ]
 
@@ -85,6 +86,7 @@
     'css/custom.css'
 ]
 
+todo_include_todos = True
 
 # HTML context:
 from os.path import basename, dirname, realpath

docs/conf.py

@@ -1,4 +1,73 @@
-Installation
-============
+Installing Sphinx
+=================
 
-This is a subject
+
+Local Installation
+==================
+
+.. tip::
+    When you need to write a lot of documentation, it's a **good idea** to do it all locally. 
+
+
+1. Cloning the Repo
+------------------------
+Clone the `sphinx-documentation-demo <https://github.com/bioteam/sphinx-documentation-demo>`_ GitHub repository into a local directory:
+
+.. code-block:: bash
+
+    git clone [email protected]:bioteam/sphinx-documentation-demo.git
+
+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.
+It's a good idea to install them in a **virtual environment**.
+
+
+
+2a. Using :code:`venv` to install
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    python -m venv sphinx_venv
+    source sphinx_venv/bin/activate
+    pip install -r requirements.txt
+
+
+
+3. Building Documentation
+-------------------------
+The documentation for the :code:`sphinx-documentation-demo` is located in :code:`docs/`.
+To build this documentation, while in the project directory, do:
+
+.. code-block:: bash
+
+    sphinx-build -M html docs/ _build
+
+This will tell Sphinx to generate static HTML documentation from :term:`rST` files within :code:`docs/` and then place them in :code:`_build`.
+You can open the file :code:`docs/index.html` on your computer to view the HTML documentation in your web browser.
+
+
+
+3a. Using :code:`sphinx-autobuild`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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**.
+
+This extension has already been included in the :code:`requirements.txt` file
+
+While in the virtual environment, run the following command:
+
+.. code-block:: bash
+
+    sphinx-autobuild docs _build
+
+This will create a local host instance which you can then access through your web browser (you can just copy/paste the http address you get from :code:`sphinx-autobuild`)
+
+Remote Build on GitHub
+======================
+
+.. todo::
+
+    Finish the guide for remote building on GitHub.

docs/guides/.DS_Store

@@ -0,0 +1,65 @@
+What is Sphinx?
+===============
+
+Sphinx lets you generate static web pages that can be hosted on sites such as `Github Pages <https://pages.github.com/>`_ and `Read the Docs <https://about.readthedocs.com/?ref=readthedocs.com>`_.
+While there are other tools that can be used to generate documentation, Sphinx is **open source**, popular, and well-supported.
+
+Some use cases for Sphinx include:
+
+
+.. grid:: 2
+    :gutter: 4
+
+    .. grid-item-card::
+        :class-header: `sd-bg-secondary sd-text-white sd-text-center`
+
+        :material-regular:`dvr;2em` Documenting Code
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        Sphinx can be used to generate documentation from `docstrings <https://peps.python.org/pep-0257/>`_. For example: Python's `code documentation <https://docs.python.org/3/library/functions.html#print>`_.
+        
+
+    .. grid-item-card::
+        :class-header: `sd-bg-secondary sd-text-white sd-text-center`
+
+        :material-regular:`auto_stories;2em` Knowledge Base
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        Sphinx can also be used more like a wiki, where reference documents can be hosted in an accessible location.
+
+    .. grid-item-card::
+        :class-header: `sd-bg-secondary sd-text-white sd-text-center`
+
+        :material-regular:`rss_feed;2em` Blogging
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        "Blog-style" posts can be integrated into any Sphinx project using the `ABlog extension <https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/ablog.html>`_.
+
+    .. grid-item-card::
+        :class-header: `sd-bg-secondary sd-text-white sd-text-center`
+
+        :material-regular:`visibility;2em` Data Visualization
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        Jupyter notebook visualizations can be embedded into Sphinx documentation using the `nbsphinx <https://nbsphinx.readthedocs.io/en/0.9.3/index.html>`_ extension.
+
+    .. grid-item-card::
+        :margin: 4 2 auto auto
+        :class-header: `sd-bg-secondary sd-text-white sd-text-center`
+        :text-align: center
+
+        :material-regular:`image;2em` Gallery
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        You can easily throw together a gallery of cards to highlight important features, links, or images. For example, `this site <https://sphinx-extensions.readthedocs.io/en/latest/>`_.
+
+How do I use Sphinx?
+====================
+.. admonition:: Why reStructuredText (rST)?
+    :class: sidebar note
+
+    This demo assumes you'll be using rST to write documentation.
+    While there is `support for Markdown <https://myst-parser.readthedocs.io/en/v0.17.1/sphinx/intro.html>`_, the grammar can be cumbersome when writing complicated :term:`directives<directive>`.
+
+Sphinx can be run locally on your laptop to generate HTML files from source code, `Markdown <https://en.wikipedia.org/wiki/Markdown>`_, or `reStructredText (rST) <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_.
+You can also run it remotely on GitHub by adding a post-commit hook to build documentation pushed to a repository. This will be expanded upon in a later tutorial.
+
+.. todo::
+
+    Add link to tutorial to build docs in GitHub
+

docs/guides/guide_installation.rst

@@ -6,13 +6,17 @@ Guides
    :maxdepth: 1
    :caption: Starting Out
 
+   guide_what_is_sphinx
    guide_installation
+   layout/index
 
 .. toctree::
    :maxdepth: 1
    :caption: References
 
    reference_directives
+   reference_glossary
+   reference_todo
 
 .. toctree::
    :maxdepth: 1

docs/guides/guide_what_is_sphinx.rst

@@ -0,0 +1,7 @@
+Documentation Layout
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   layout_basic

docs/guides/index.rst

@@ -0,0 +1,120 @@
+Layout Overview
+=============================
+.. note::
+    :class: sidebar
+
+    The Sphinx theme (`PyData <https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html>`_ in our case) can also affect how documents are shown in the layout.
+
+The documentation you see on this website is built from the `docs <https://github.com/bioteam/sphinx-documentation-demo/tree/main/docs>`_ directory located in the project.
+
+Sphinx compiles the :term:`rST` files inside of this directory and generates static HTML files.
+The file layout of the :code:`docs/` directory, along with "toctrees" (which we will cover this later), will **determine the website layout of the documentation**.
+
+Therefore it's important to understand how to organize files within the :code:`docs/` directory so that Sphinx knows where to display them.
+We'll cover this over the course of several short tutorials so that you can learn how to:
+
+..
+    .. list-table:: 
+        :header-rows: 1
+
+        * - **Add a new...**
+        * - Tab to the top navigation bar
+        * - Page to the left navigation bar
+        * - Section to the left navigation bar
+
+* Add a new tab to the top navigation bar
+* Add a new page to the left navigation bar
+* Add a new section to the left navigation bar
+
+Before that, we review each of the major layout components in the sections below.
+
+Top Navigation Bar
+==================
+
+.. figure:: images/layout_top.png
+        :class: sd-border-2
+
+        The top navigation bar (highlighted in red)
+
+
+Logo
+----
+
+The "logo" is located in the upper-left-hand corner of the page.
+Typically this is just text, but you can also add an icon.
+To change the text that you see:
+
+1. Go into :code:`docs/conf.py`
+2. In html_theme_options...
+3. Change the text stored in the "logo" key: 
+
+.. image:: images/logo_loc.png
+    :class: sd-border-2
+
+
+
+.. seealso::
+
+    `PyData's guide on changing the logo <https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/branding.html>`_
+
+
+
+Tabs
+----
+.. figure:: images/tabs.png
+    :class: sd-border-2
+
+    This project has three tabs, although two of them are for demonstration purposes.
+
+
+
+You can organize content into different "tabs".
+For example, a code project could be partitioned into a "Tutorials" tab (for in-depth documentation) and an "API" tab (for documenting specific functions)
+
+A tab is created for each "toctree" in the root index file :code:`docs/index.rst`. 
+This will be covered in a later tutorial.
+
+.. todo::
+
+    Link to the tabs tutorial
+
+
+Search Bar
+----------
+.. warning::
+    :class: sidebar
+
+    The search bar doesn't work well when you are viewing documentation **locally** on your computer.
+
+Sphinx comes with built-in search functionality. 
+Users that enter text into the search bar in the upper-right-hand corner can search across multiple documentation pages.
+
+Left Navigation Bar
+===================
+.. figure:: images/layout_left.png
+        :class: sd-border-2
+
+        The left navigation bar (highlighted in red)
+
+
+The left navigation bar allows users to navigate between documents that have been indexed within a "toctree" (more on this later). 
+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
+
+        The right navigation bar (highlighted in red)
+
+
+The right navigation bar allows users to navigation between **different sections within the current page**.
+This is automatically generated based on section headers specified within the page's :term:'rST' file.
+
+..
+    .. image:: images/tab2_top.png
+        :class: sd-border-2
+
+    | 
+
+

docs/guides/layout/.DS_Store

@@ -0,0 +1,29 @@
+Glossary
+========
+
+.. Glossary::
+
+    Directive
+        Directives are special commands that can be embedded as text into an rST document.
+        They can be used to dictate how content in the document gets formatted by Sphinx. 
+
+        For example, having this in a document:
+
+        .. code-block:: rst
+
+            .. admonition:: title
+
+                content
+
+        ... would generate this:
+
+        .. admonition:: title
+
+            content
+
+
+    rST
+       reStructuredText is a plaintext markup language that Sphinx can use to generate documentation.
+       This will be the standard way we write documentation in this project. Mardown is an alternative langauge.
+
+       See this `cheat sheet <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>`_ for the common markup used in rST files.

docs/guides/layout/images/.DS_Store

@@ -0,0 +1,7 @@
+Todo List
+=================
+
+This will generate a list of todo entries when todo_include_todos is set to "True" in config.py
+
+
+.. todolist::

docs/guides/layout/images/layout_left.png

@@ -1,4 +1,29 @@
 Subject_1
 ==========
 
-This is a subject
+This is a long page to test out some of the features of Sphinx.
+
+
+Section 1
+=========
+
+Subsection 1
+------------
+
+Sub-Subsection 1
+~~~~~~~~~~~~~~~~
+
+Sub-Subsection 2
+~~~~~~~~~~~~~~~~
+
+Sub-Subsection 3
+~~~~~~~~~~~~~~~~
+
+Subsection 2
+------------
+
+Section 2
+============
+
+Subsection 3
+------------