Improving user and developer guides for zstash

docs/source/contributing.rst → docs/source/dev_guide/contributing_to_docs.rst

@@ -72,7 +72,7 @@ using Sphinx, you can refer to
     $ # Check the `_build/html` folder for all generated versioned docs
     $ # Open `_build/html/<your-branch>/index.html` to view in browser
 
-   .. figure:: _static/docs-version-selector.png
+   .. figure:: _static/figures/docs-version-selector.png
       :alt: Docs version selector
 
       Docs version selector dropdown in the bottom left-hand corner
@@ -106,20 +106,26 @@ for a new repository. (Adapted from `Sphinx documentation on GitHub
 
 Create Sphinx conda environment (see above).
 
-Create a new git branch (gh-pages): ::
+Create a new git branch (gh-pages): 
 
-  $ git branch gh-pages
-  $ git checkout gh-pages
+  .. code-block:: bash
 
-Clear out anything from the main branch and start fresh ::
+    git branch gh-pages
+    git checkout gh-pages
 
-  $ git symbolic-ref HEAD refs/heads/gh-pages
-  $ rm .git/index
-  $ git clean -fdx
+Clear out anything from the main branch and start fresh
 
-Create documentation ::
+  .. code-block:: bash
 
-  $ sphinx-quickstart
+    git symbolic-ref HEAD refs/heads/gh-pages
+    rm .git/index
+    git clean -fdx
+
+Create documentation
+
+  .. code-block:: bash
+
+    sphinx-quickstart
 
 accept suggested default options, except ::
 
@@ -129,40 +135,54 @@ Edit Makefile and change BUILDIR ::
 
   BUILDDIR = docs
 
-Remove old build directory ::
+Remove old build directory
+
+  .. code-block:: bash
+
+    rmdir build
 
-  $ rmdir build
+Change the Sphinx theme to 'ReadTheDocs'. Edit 'source/conf.py and change
 
-Change the Sphinx theme to 'ReadTheDocs'. Edit 'source/conf.py and change ::
+  .. code-block:: python
 
-  html_theme = 'alabaster'
+    html_theme = 'alabaster'
 
-to ::
+to
 
-  import sphinx_rtd_theme
-  html_theme = "sphinx_rtd_theme"
-  html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+  .. code-block:: python
 
-Try building documentation ::
+    import sphinx_rtd_theme
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
-  $ make html
+Try building documentation
+
+  .. code-block:: bash
+
+    make html
 
 Create an empty .nojekyll file to indicate to Github.com that this
-is not a Jekyll static website: ::
+is not a Jekyll static website:
+
+  .. code-block:: bash
 
-  $ touch .nojekyll
+    touch .nojekyll
 
-Create a top-level re-direction file: ::
+Create a top-level re-direction file:
 
-  $ vi index.html
+  .. code-block:: bash
+
+    vi index.html
 
 with the following: ::
 
   <meta http-equiv="refresh" content="0; url=./docs/html/index.html" />
 
-Commit and push back to Github: ::
+Commit and push back to Github:
+
+  .. code-block:: bash
 
-  $ git add .
-  $ git commit
-  $ git push origin gh-pages
+    git add .
+    git commit
+    git push origin gh-pages
 

docs/source/dev_guide/index.rst

@@ -2,10 +2,15 @@
 Developer Guide
 ###############
 
+Use this guide for repository conventions, testing, release work, and
+implementation details that are mainly useful to contributors.
+
 .. toctree::
    :maxdepth: 2
 
-   project-standards
+   project_standards
    ci
-   release_testing
-   release
+   tar_tracking_modes
+   testing
+   releases/index
+   contributing_to_docs

docs/source/dev_guide/project-standards.rst → docs/source/dev_guide/project_standards.rst

@@ -11,7 +11,7 @@ Version Control (VC)
 
 The repository uses a fork-based Git workflow with tag releases.
 
-.. figure:: git-flow.svg
+.. figure:: /_static/figures/git-flow.svg
    :alt: Git Flow Diagram
 
 Guidelines for VC
@@ -39,37 +39,45 @@ The repository uses the ``pre-commit`` package to manage pre-commit hooks.
 These hooks help enforce quality assurance standards and identify simple issues
 at the commit level before submitting code reviews.
 
-.. figure:: pre-commit-flow.svg
+.. figure:: /_static/figures/pre-commit-flow.svg
    :alt: Pre-commit Flow Diagram
 
    ``pre-commit`` Flow
 
 Helpful ``pre-commit`` Commands
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Install into your cloned repo ::
+Install into your cloned repo
 
-    conda activate zstash_dev
-    pre-commit install
+    .. code-block:: bash
 
-Automatically run all pre-commit hooks (just commit) ::
+        conda activate zstash_dev
+        pre-commit install
+
+Automatically run all pre-commit hooks (just commit)
+
+  .. code-block:: bash
 
     # Tip: If there is an issue with pre-commit, you can bypass with the `--no-verify` flag. Please do NOT use this on a regular basis.
     git commit -m '...'
 
-.. figure:: ../_static/pre-commit-passing.png
+.. figure:: ../_static/figures/pre-commit-passing.png
    :alt: pre-commit Output
 
    ``pre-commit`` Output
 
-Manually run all pre-commit hooks ::
+Manually run all pre-commit hooks
+
+    .. code-block:: bash
+
+        pre-commit run --all-files
 
-    pre-commit run --all-files
+Run individual hook
 
-Run individual hook ::
+    .. code-block:: bash
 
-    # Available hook ids: trailing-whitespace, end-of-file-fixer, check-yaml, black, isort, flake8, mypy
-    pre-commit run <hook_id>
+        # Available hook ids: trailing-whitespace, end-of-file-fixer, check-yaml, black, isort, flake8, mypy
+        pre-commit run <hook_id>
 
 Squash and Rebase Commits
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -93,36 +101,44 @@ How to squash and rebase commits
 
 Assuming that you followed :ref:`"(b) Development Environment" <dev-env>`:
 
-1. Sync ``main`` with the main repo's ``main`` ::
+1. Sync ``main`` with the main repo's ``main``
 
-    git checkout main
-    git rebase <upstream-origin>/main
-    git push -f <fork-origin> main
+    .. code-block:: bash
 
-2. Get the SHA of the commit OR number of commits to rebase to ::
+        git checkout main
+        git rebase <upstream-origin>/main
+        git push -f <fork-origin> main
 
-    git log --graph --decorate --pretty=oneline --abbrev-commit
+2. Get the SHA of the commit OR number of commits to rebase to
 
-3. Squash commits::
+    .. code-block:: bash
 
-    git rebase -i [SHA]
+        git log --graph --decorate --pretty=oneline --abbrev-commit
 
-    # OR
+3. Squash commits
 
-    git rebase -i HEAD~[NUMBER OF COMMITS]
+    .. code-block:: bash
+
+        git rebase -i [SHA]
+        # OR:
+        git rebase -i HEAD~[NUMBER OF COMMITS]
 
 4. Make sure your squashed commit messages are refined
 
-5. Rebase branch onto ``main`` ::
+5. Rebase branch onto ``main``
+
+    .. code-block:: bash
 
-    git checkout <branch-name>
-    git rebase main
-    git push -f <fork-origin> <branch-name>
+        git checkout <branch-name>
+        git rebase main
+        git push -f <fork-origin> <branch-name>
 
-6. Force push to remote branch ::
+6. Force push to remote branch
 
-    # You have to force push because the rebase rewrites the commit SHAs
-    git push -f <fork-origin> <branch-name>
+    .. code-block:: bash
+
+        # You have to force push because the rebase rewrites the commit SHAs
+        git push -f <fork-origin> <branch-name>
 
 Source:
 https://blog.carbonfive.com/always-squash-and-rebase-your-git-commits/
@@ -142,10 +158,11 @@ Helpful Commands
 ~~~~~~~~~~~~~~~~
 
 Run a tool
-    ::
 
-       # Available tool names: black, flake8, isort, mypy
-       <tool_name> .
+    .. code-block:: bash
+
+        # Available tool names: black, flake8, isort, mypy
+        <tool_name> .
 
 .. _ci-cd: