Merge pull request #39 from LLNL/doc-cleanup

Doc cleanup

docs/Pipfile

@@ -7,6 +7,8 @@ verify_ssl = true
 
 [packages]
 sphinx-rtd-theme = "*"
+sphinx = "*"
+docutils = "==0.16"
 
 [requires]
 python_version = "3.8"

docs/_build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: d29921abf232c0a85e45f30dc14dc92e
+config: 575d3c6b1fe532d8213d4a2ed68a45d1
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/html/_sources/contribute.rst.txt

@@ -0,0 +1,59 @@
+.. Copyright 2022 Lawrence Livermore National Security, LLC
+
+.. _contribute:
+
+===========================
+Contribute to Existing Docs
+===========================
+
+To contribute to a repo that already has Sphinx/RtD set up, you will need to initiate a temporary virtual environment where you can build docs locally before pushing your changes.
+
+------------------------
+Install requirements.txt
+------------------------
+After forking/cloning the repo normally, locate the ``requirements.txt`` file in the project directory and navigate into that folder.
+
+Create a virtual environment for the repo's docs::
+
+    $ pipenv install -r requirements.txt
+
+.. note::
+
+    * An error means a requirement is missing from your system or you are not in the correct directory.
+    * A repo's *gemfile* says what you need to install; the *lockfile* conveys the particular versions needed.
+
+Activate the virtual environment::
+
+    $ pipenv shell
+
+------------------
+Build Docs Locally
+------------------
+
+Build the docs as static HTML files for editing::
+
+    $ pipenv run make html
+
+The resulting information should indicate that the docs are ready in ``_build/html``.
+
+.. note::
+
+    * Run this in the directory where the ``Makefile`` lives.
+    * Run this again after installing any missing requirements.
+    * Run this when you want to view the docs (i.e., as a QA check before committing and opening a PR).
+    * Run this whenever you need to rebuild docs (e.g., after un-staging a staged file).
+    * Prepend ``pipenv run`` when building docs via a virtual environment (otherwise, it would just be ``make html``).
+
+You can open a file in your browser to QA your changes::
+
+    $ open _build/html/Filename.html
+
+Commit your edits and submit a PR normally.
+
+---------------------
+When Finished Editing
+---------------------
+
+You may want to update your ``.gitignore`` file with any changes to system files that you do not want committed.
+
+Exit the virtual environment before switching to another repo by pressing ``ctrl-d``. *If you don't do this, repo B will look at the requirements in repo A instead of finding its own.*

docs/_build/html/_sources/index.rst.txt

@@ -1,4 +1,4 @@
-.. Copyright 2020 Lawrence Livermore National Security, LLC
+.. Copyright 2022 Lawrence Livermore National Security, LLC
 
 =================
 LLNL RtD Template
@@ -11,4 +11,9 @@ This documentation site and the files associated with the `.github repo <https:/
    :caption: Contents:
 
    setup_steps
+   contribute
    resources
+
+.. note::
+
+   This site is running Sphinx v2.0.1 but downgraded to Docutils v0.16 for ``sphinx_rtd_theme``. Docutils v0.17 has a `bug <https://github.com/readthedocs/sphinx_rtd_theme/issues/1115>`_ in which bulleted (unordered) lists are not rendered properly.

docs/_build/html/_sources/resources.rst.txt

@@ -1,10 +1,10 @@
-.. Copyright 2020 Lawrence Livermore National Security, LLC
+.. Copyright 2022 Lawrence Livermore National Security, LLC
 
 .. _resources:
 
-======================
-RtD & Sphinx Resources
-======================
+=======================
+Documentation Resources
+=======================
 
 These sites are good places to learn about Read the Docs (RtD), Sphinx, and all the things you can do in .rst files:
 
@@ -15,3 +15,12 @@ These sites are good places to learn about Read the Docs (RtD), Sphinx, and all
 * `Sphinx tutorial <https://sphinx-tutorial.readthedocs.io/>`_
 * `reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
 * `Graphviz syntax <https://rich-iannone.github.io/DiagrammeR/graphviz_and_mermaid.html>`_
+
+To write more effective software documentation generally, here are some useful sites:
+
+* The `18F Content Guide <https://content-guide.18f.gov/>`_ houses best practices for software documentation focused on user experiences and needs, particularly as related to government websites.
+* `Write the Docs <https://www.writethedocs.org/>`_, a community focused on communication and documentation, has a `catalog of learning resources <https://www.writethedocs.org/about/learning-resources/>`_ (including videos and tutorials) as well as a robust `documentation guide <https://www.writethedocs.org/guide/>`_. This community also has a `GitHub repo <https://github.com/writethedocs>`_.
+* `Docs as Code <https://www.docslikecode.com/>`_ provides resources for development teams to build documentation repeatably and consistently across multiple platforms.
+* The `Documentation System <https://documentation.divio.com/>`_ emphasizes four types of documentation: tutorials, how-to guides, technical reference, and explanation documents. The site provides examples of and tips for each.
+* The `Good Docs Project <https://thegooddocsproject.dev/>`_, to which you can `contribute <https://thegooddocsproject.dev/contribute>`_, includes templates and writing instructions for documenting open source software. The organization's templates go through a rigorous writing, reviewing, and refining process.
+* The `Beautiful Docs repo <https://github.com/PharkMillups/beautiful-docs>`_ has a list of language- and program-specific documentation resources.

docs/_build/html/_sources/setup_steps.rst.txt

@@ -1,4 +1,4 @@
-.. Copyright 2020 Lawrence Livermore National Security, LLC
+.. Copyright 2022 Lawrence Livermore National Security, LLC
 
 .. _setup_steps:
 
@@ -10,38 +10,40 @@ The process of creating a Read the Docs (RtD) site is widely documented (see als
 
 The basic steps are:
 
-A. Create repo on GitHub or create local directory to existing repo
-B. Install Sphinx
-C. Build and configure doc files
-D. Set up GitHub and RtD webhook integration
-E. Create .rst files
+#. Create repo on GitHub or create local directory to existing repo
+#. Install Sphinx
+#. Build and configure doc files
+#. Set up GitHub and RtD webhook integration
+#. Create .rst files
 
 ------------------------
-A. Create Repo/Directory
+1. Create Repo/Directory
 ------------------------
 
-The instructions below assume that developers understand step *A*.
+The instructions below assume that developers understand step 1.
 
 -----------------
-B. Install Sphinx
+2. Install Sphinx
 -----------------
-1. Create a **/docs** folder in your project. Then ``cd docs`` to complete most of the remaining steps (exceptions are noted below).
-2. Install `RtD template from GitHub <https://github.com/readthedocs/sphinx_rtd_theme>`_ using Sphinx (``pipenv install sphinx-rtd-theme``).
-3. Initiate Sphinx quickstart (``pipenv run sphinx-quickstart``). Answer the questions that follow installation, such as selecting No for setting up build and source separately.
-4. Move the makefile into the ``/docs`` folder if it's not there already.
-5. Confirm the Sphinx version (``pipenv run sphinx-build --version``).
-6. Confirm that docs can build locally (``pipenv run make html``). You must be in the /docs directory for this to work. Unlike viewing a site on a local port, where newly saved changes auto-regenerate the site, you will need to run this command after every saved change in order to see the new change.
+
+* Create a **/docs** folder in your project. Then ``cd docs`` to complete most of the remaining steps (exceptions are noted below).
+* Install `RtD template from GitHub <https://github.com/readthedocs/sphinx_rtd_theme>`_ using Sphinx (``pipenv install sphinx-rtd-theme``).
+* Initiate Sphinx quickstart (``pipenv run sphinx-quickstart``). Answer the questions that follow installation, such as selecting No for setting up build and source separately.
+* Move the makefile into the ``/docs`` folder if it's not there already.
+* Confirm the Sphinx version (``pipenv run sphinx-build --version``).
+* Confirm that docs can build locally (``pipenv run make html``). You must be in the ``/docs`` directory for this to work. Unlike viewing a site on a local port, where newly saved changes auto-regenerate the site, you will need to run this command after every saved change in order to see the new change.
 
 --------------------------------
-C. Build and Configure Doc Files
+3. Build and Configure Doc Files
 --------------------------------
-1. Update the **conf.py** file. For instance, you can change the RtD theme (``html_theme``). In the General Configuration section, add the name of master .rst file::
+
+* Update the **conf.py** file. For instance, you can change the RtD theme (``html_theme``). In the General Configuration section, add the name of master .rst file::
 
     # Tells Sphinx the name of the master .rst file.
     master_doc = 'index'
 
-2. Create the **.gitignore** file (``touch .gitignore``) so your commits will include only source files, not the HTML-rendered files (`GitHub instructions <https://help.github.com/en/articles/ignoring-files>`_).
-3. Create the **requirements.txt** file to specify dependency versions (`RtD instructions <https://docs.readthedocs.io/en/stable/config-file/v2.html?highlight=requirements.txt#requirements-file>`_). This file usually contains information like this::
+* Create the **.gitignore** file (``touch .gitignore``) so your commits will include only source files, not the HTML-rendered files (`GitHub instructions <https://help.github.com/en/articles/ignoring-files>`_).
+* Create the **requirements.txt** file to specify dependency versions (`RtD instructions <https://docs.readthedocs.io/en/stable/config-file/v2.html?highlight=requirements.txt#requirements-file>`_). This file usually contains information like this::
 
     # These dependencies should be installed using pip in order
     # to build the documentation.
@@ -51,33 +53,35 @@ C. Build and Configure Doc Files
     sphinx-rtd-theme==0.4.3
     python-levenshtein
 
-4. Create the **.readthedocs.yml** file in the *top directory* of the repo. Paste in the `V2 content <https://docs.readthedocs.io/en/stable/config-file/v2.html>`_.
-5. Commit configuration changes, then open and merge PR before moving on.
+* Create the **.readthedocs.yml** file in the *top directory* of the repo. Paste in the `V2 content <https://docs.readthedocs.io/en/stable/config-file/v2.html>`_.
+* Commit configuration changes, then open and merge PR before moving on.
 
 --------------------------------
-D. Establish Webhook Integration
+4. Establish Webhook Integration
 --------------------------------
+
 This process generates a **readthedocs.io** URL for your project, which you can then link to in your repo's README file.
 
-1. Log into the `RtD website <https://readthedocs.org/>`_ via your GitHub account. You will have to go through an account verification process the first time.
-2. My Projects > Import a Project > select your repo. You may need to refresh the list or filter out an organization.
-3. Enter repo name and GitHub URL if not pre-populated. Confirm **.git** is appended to the end of the URL.
-4. Follow `webhook creation instructions <https://docs.readthedocs.io/en/stable/webhooks.html#webhook-creation>`_. When you try to build the docs for the first time, you may get an error: *fatal: could not read Username for 'https://github.com': terminal prompts disabled*. So you must configure the webhook to recognize GitHub's 2FA via ``git config --global --add url."git@github.com:".insteadOf "https://github.com/"``.
-5. Add doc build status to your repo's README file. Open the file and paste in the badge syntax (where **name** is your repo)::
+* Log into the `RtD website <https://readthedocs.org/>`_ via your GitHub account. You will have to go through an account verification process the first time.
+* My Projects > Import a Project > select your repo. You may need to refresh the list or filter out an organization.
+* Enter repo name and GitHub URL if not pre-populated. Confirm **.git** is appended to the end of the URL.
+* Follow `webhook creation instructions <https://docs.readthedocs.io/en/stable/webhooks.html#webhook-creation>`_. When you try to build the docs for the first time, you may get an error: *fatal: could not read Username for 'https://github.com': terminal prompts disabled*. So you must configure the webhook to recognize GitHub's 2FA via ``git config --global --add url."git@github.com:".insteadOf "https://github.com/"``.
+* Add doc build status to your repo's README file. Open the file and paste in the badge syntax (where **name** is your repo)::
 
     [![Documentation Status](https://readthedocs.org/projects/name/badge/?version=latest)](https://name.readthedocs.io/en/latest/?badge=latest)
 
-6. Confirm that docs still build locally, then open and merge PR.
-7. On your RtD dashboard, select the project and initiate a build to test: Projects > your repo > Builds > Build Version.
-8. You may want to change some of RtD's advanced settings, such as specifying which version is considered "latest" or which branch is the default. Projects > your repo > Admin > Advanced Settings. 
+* Confirm that docs still build locally, then open and merge PR.
+* On your RtD dashboard, select the project and initiate a build to test: Projects > your repo > Builds > Build Version.
+* You may want to change some of RtD's advanced settings, such as specifying which version is considered "latest" or which branch is the default. Don't forget to update this area if you change the name of your default branch (e.g., ``master`` to ``main``). Projects > your repo > Admin > Advanced Settings. 
 
 ---------------------------------
-E. Create and Populate .rst Files
+5. Create and Populate .rst Files
 ---------------------------------
+
 All documentation files should contain your repo's copyright date(s) and license information at the top, set off by two periods (``..``).
 
-1. Create the **index.rst** file (or whatever file name you specified as the master file in step *C1* above).
-2. Set up table of contents (TOC), specifying how many levels deep you want to expose. For example, this site's TOC looks like this::   
+* Create the **index.rst** file (or whatever file name you specified as the master file in step *C1* above).
+* Set up table of contents (TOC), specifying how many levels deep you want to expose. For example, this site's TOC looks like this::   
 
     .. toctree::
        :maxdepth: 2
@@ -86,27 +90,27 @@ All documentation files should contain your repo's copyright date(s) and license
        setup_steps
        resources
 
-3. Create subordinate .rst files with reference to the link you established in the TOC. The page doesn't have to have the same title as the file name. For example, this page is titled *Steps for Setting up Docs* while the TOC linkage is based on the file name of **setup_steps.rst**::
+* Create subordinate .rst files with reference to the link you established in the TOC. The page doesn't have to have the same title as the file name. For example, this page is titled *Steps for Setting up Docs* while the TOC linkage is based on the file name of **setup_steps.rst**::
 
     .. _setup_steps:
 
-4. Now you can begin a cycle of adding/editing files, building locally, and pushing to GitHub. The configuration settings above should trigger automatic RtD builds with every commit or PR, but you can always manually build the docs site from your RtD dashboard.
+* Now you can begin a cycle of adding/editing files, building locally, and pushing to GitHub. The configuration settings above should trigger automatic RtD builds with every commit or PR, but you can always manually build the docs site from your RtD dashboard.
 
 ^^^^^^
 Images
 ^^^^^^
 
 Adding inline images to your documentation is as simple as saving, then referencing, the image file at the proper level of the repo directory. This repo's images reside in the ``/docs`` folder.
 
-* Favicon (displays in the browser tab): In the ``confy.py`` file, add the image file name::
+*Favicon* (displays in the browser tab); in the ``confy.py`` file, add the image file name::
 
     html_favicon = 'OS-icon-color.png'
 
-* Home image (displays in the top left corner): Also in the ``confy.py`` file::
+*Home image* (displays in the top left corner), also in the ``confy.py`` file::
 
     html_logo = 'OS-logo-horizontal-white.png'
 
-* Inline image, for which you can specify dimensions and alignment::
+*Inline image*, for which you can specify dimensions and alignment::
 
     .. image:: OS-inline-example.png
         :width: 400px