Merge pull request #113 from andthum/docs/update

andthum · web-flow · commit 312b663c989d · 2023-02-13T19:25:30.000+01:00
Update Documentation
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -22,7 +22,7 @@ Release-Wise List of Authors
 Upcoming release
 
     * Add your name, if you have contributed to the upcoming release.
-      Athors are ordered alphabetically by their full name.
+      Authors are ordered alphabetically by their full name.
       Additionally, add your name to the `authors` option of the
       `[project]` section in `pyproject.toml`.
     * Andreas Thum
diff --git a/docs/Makefile b/docs/Makefile
@@ -7,7 +7,7 @@ SPHINXBUILD        = sphinx-build
 SOURCEDIR          = source
 BUILDDIR           = build
 AUTOSUMDIR_PATTERN = _sphinx_autosummary*
-AUTOSUMDIR         = $(shell find $(SOURCEDIR) -name "$(AUTOSUMDIR_PATTERN)")
+AUTOSUMDIR         = $(shell find $(SOURCEDIR) -type d -name "$(AUTOSUMDIR_PATTERN)")
 
 # Put this first so that "make" without argument is like "make help".
 help:
diff --git a/docs/README.rst b/docs/README.rst
@@ -34,5 +34,13 @@ After installing all requirements, the documentation can be built via
     # Deactivate the virtual Python environment.
     deactivate
 
+To clean the build directory and remove all automatically generated
+files, run in the ``docs/`` directory the following commands.
+
+.. code-block:: bash
+
+    make clean
+    make clean_autosum
+
 
 .. _Sphinx: https://www.sphinx-doc.org/
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
@@ -1,5 +1,5 @@
 # Requirements to build hpcss' documentation.
 
-sphinx >=3.0, <7.0
-sphinx-rtd-theme <2.0
-tomlkit < 1.0
+sphinx >=5.0, <7.0
+sphinx-rtd-theme >=1.0, <2.0
+tomlkit >=0.1, < 1.0
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -20,6 +20,7 @@
 # Standard libraries
 import os
 import sys
+from datetime import datetime
 
 # Third-party libraries
 import tomlkit
@@ -32,11 +33,12 @@
 # is relative to the  documentation root, use os.path.abspath to make it
 # absolute, like shown here.
 
-# Recursively import all directories containing Pyhon scripts.
+# Recursively import all directories containing Python scripts.
 directories = ("analysis", "python", "simulation")
 for directory in directories:
-    for path in os.walk(os.path.abspath("../../" + directory)):
-        sys.path.insert(1, path[0])
+    for root, _dirs, _files in os.walk(os.path.abspath("../../" + directory)):
+        if os.path.basename(os.path.normpath(root)) not in ("", "__pycache__"):
+            sys.path.insert(1, root)
 
 
 # -- Project information -----------------------------------------------
@@ -50,7 +52,8 @@
 author = ", ".join(str(dct["name"]) for dct in metadata["project"]["authors"])
 
 # A copyright statement in the style "2008, Author Name".
-years = "2021, 2022"
+now = datetime.now().year
+years = "2021-{}, ".format(now)
 copyright = "Copyright (C) " + years + " " + author  # noqa: A001
 
 # The short X.Y version
@@ -228,7 +231,7 @@
 default_role = None
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = "3.0"
+needs_sphinx = "5.0"
 
 # If true, Sphinx will warn about all references where the target cannot
 # be found.  This includes also argument types like "array_like",
@@ -304,7 +307,7 @@
 # large.
 html_favicon = "../logo/hpcss_favicon_32x32.png"
 
-# A list of CSS files.  Filenams must be relative to html_static_path.
+# A list of CSS files.  Filenames must be relative to html_static_path.
 html_css_files = ["custom.css"]
 
 # A list of paths that contain custom static files (such as style sheets
diff --git a/docs/source/doc_pages/dev_guide/build_docs.rst b/docs/source/doc_pages/dev_guide/build_docs.rst
@@ -30,3 +30,11 @@ After installing all requirements, the documentation can be built via
     make doctest
     # Deactivate the virtual Python environment.
     deactivate
+
+To clean the build directory and remove all automatically generated
+files, run in the :file:`docs/` directory the following commands.
+
+.. code-block:: bash
+
+    make clean
+    make clean_autosum
diff --git a/docs/source/doc_pages/dev_guide/code_guidelines_py.rst b/docs/source/doc_pages/dev_guide/code_guidelines_py.rst
@@ -75,7 +75,7 @@ Other Python Code Guidelines
         - Constant variable names: ``UPPER_CASE_WITH_UNDERSCORES``
         - Underscores:
 
-            + ``_``: For throwaway varibales, i.e. for variables that
+            + ``_``: For throwaway variables, i.e. for variables that
               will never be used.  For instance if a function returns
               two values, but only one is of interest.
             + ``single_trailing_underscore_``: Used by convention to
diff --git a/docs/source/doc_pages/dev_guide/dev_guide.rst b/docs/source/doc_pages/dev_guide/dev_guide.rst
@@ -20,7 +20,7 @@ mess.
     comfortable with that *before* you contribute to the project.
 
 .. toctree::
-    :caption: Table of Contens
+    :caption: Table of Contents
     :name: dev-guide-toc
     :maxdepth: 1
     :hidden:
diff --git a/docs/source/doc_pages/dev_guide/dev_install.rst b/docs/source/doc_pages/dev_guide/dev_install.rst
@@ -60,7 +60,7 @@ interfere with other Python packages installed on your computer.
 3. Install the Development Packages
 -----------------------------------
 
-Install the pacakges required for developing the project (i.e.
+Install the packages required for developing the project (i.e.
 formatters, linters, testing packages, pre-commit, etc.) into the
 :ref:`development environment <set-up-dev-env-label>`:
 
@@ -84,6 +84,20 @@ this project by typing:
 
     pre-commit install --install-hooks
 
+.. note::
+
+    You might need to install
+    `markdownlint <https://github.com/markdownlint/markdownlint>`_ (a
+    Ruby gem package) in order to get the markdownlint pre-commit hook
+    running.
+
+    Software required for installing `RubyGems <https://rubygems.org/>`_
+    packages:
+
+    * Ruby developer package
+    * `Ruby <https://www.ruby-lang.org/en/>`_
+    * `RubyGems <https://rubygems.org/>`_
+
 You can check if pre-commit works properly by running
 
 .. code-block:: bash
diff --git a/docs/source/doc_pages/dev_guide/doc_guidelines.rst b/docs/source/doc_pages/dev_guide/doc_guidelines.rst
@@ -32,7 +32,7 @@ In short:
     * Use docstrings to explain *what* the code does and *how to use*
       it.
 
-      Documentation is inteded to be read by users that don't
+      Documentation is intended to be read by users that don't
       necessarily know anything about programming.  Especially, they
       don't want to read the source code.  Think about what you would
       like to know when using the code from someone else.
diff --git a/docs/source/doc_pages/dev_guide/git_workflow.rst b/docs/source/doc_pages/dev_guide/git_workflow.rst
@@ -105,16 +105,16 @@ Topic branch naming conventions:
       ``release``, ``rel``, ``fix``, ``hotfix``, ``bug``, ``bugfix``,
       ``feature``, ``feat``, ``refactor``, ``ref``, ``documentation``,
       ``docs``, ``doc``, ``dependencies``, ``dependency``,
-      ``dependend``, ``dep``, ``chore``, ``maintenance``, because these
+      ``dependent``, ``dep``, ``chore``, ``maintenance``, because these
       are (more or less) commonly used names for special branches or
       branch groups.
-    * Use slashes to sparate parts of your branch name.  However, be
+    * Use slashes to separate parts of your branch name.  However, be
       aware of the following limitation:  If a branch ``spam`` exists,
       no branch named ``spam/eggs`` can be created.  Likewise, if a
       branch ``spam/eggs`` exists, no branch named ``spam`` can be
       created (but ``spam/spam`` is possible).  The reason is that
       branches are implemented as paths.  You cannot create a directory
-      ``spam`` if a file ``spam`` already exsits and the other way
+      ``spam`` if a file ``spam`` already exists and the other way
       round.  This means, once you started branch naming without a
       sub-token, you cannot add a sub-token later.  This is the reason
       why you should never name your branches simply ``fix``, ``feat``,
@@ -133,7 +133,7 @@ Topic branch naming conventions:
           work.
 
     * Use sub-tokens where applicable and meaningful.
-    * If you adress a specific issue or feature request, reference this
+    * If you address a specific issue or feature request, reference this
       in your branch name, e.g. ``feat/issue/n15``, but
     * Do **not** use bare numbers as one part of your branch name, e.g.
       do **not** name your branch ``feat/issue/15``.  Otherwise,
@@ -217,7 +217,7 @@ Commit message conventions:
       present tense.  It should not end with a period.
     * Start the summary line with "[Path]: Change", e.g.
       "[lmod/palma/README.rst]: Fix Typo".  In this way other developers
-      and maintainers immediatly know which file has been changed.  If
+      and maintainers immediately know which file has been changed.  If
       you have a complex commit affecting several files, break it down
       into smaller commits (see above).  If the path is too long to get
       the summary line within 50 characters, only name the file that has
@@ -264,7 +264,7 @@ rebase_ your topic branch onto the target branch (which is usually the
 9. Push Your Commits to Your Fork on GitHub
 -------------------------------------------
 
-Immediatly after rebasing, push your changes to your fork's remote
+Immediately after rebasing, push your changes to your fork's remote
 repository:
 
 .. code-block:: bash
diff --git a/docs/source/doc_pages/dev_guide/test_guidelines.rst b/docs/source/doc_pages/dev_guide/test_guidelines.rst
@@ -58,7 +58,7 @@ Doctests
 ^^^^^^^^
 
 We use :mod:`doctest` to check whether the code examples given in the
-documentation work as expected.  Sphinx already brings a convient
+documentation work as expected.  Sphinx already brings a convenient
 `extension
 <https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html>`__
 to run doctest on all our example codes.  Simply do:
diff --git a/docs/source/doc_pages/dev_guide/versioning.rst b/docs/source/doc_pages/dev_guide/versioning.rst
@@ -3,10 +3,13 @@
 Versioning
 ==========
 
-.. note::
+.. contents:: Site Contents
+    :depth: 2
+    :local:
 
-    New versions can only be released by project maintainers that have
-    write access to the upstream repository.
+
+Versioning Scheme
+-----------------
 
 This project uses `semantic versioning`_.  Given a version number
 MAJOR.MINOR.PATCH, we increment the
@@ -36,34 +39,72 @@ specifiers can be appended.
 Publishing a New Release
 ------------------------
 
+.. note::
+
+    New versions can only be released by project maintainers that have
+    write access to the upstream repository.
+
 Follow these steps when publishing a new release.
 
 
-1. Update the Change Log
-^^^^^^^^^^^^^^^^^^^^^^^^
+1. Update the Version Number
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create a new branch out of ``main`` named
+``chore/release/vMAJOR.MINOR.PATCH``.
+
+.. code:: bash
+
+    git checkout main
+    git checkout -b chore/release/vMAJOR.MINOR.PATCH
+
+Update :file:`AUTHORS.rst` to list all authors that have contributed to
+the new release and commit the changes to the new branch.
+
+Add authors that have contributed for the first time to the list of
+authors in the :file:`pyproject.toml` file and commit the changes to the
+new branch.
+
+Update the version number in :file:`pyproject.toml` to the new
+MAJOR.MINOR.PATCH version and commit the changes to the new branch.
 
-.. todo::
+Push the branch to the upstream repository.
 
-    Establish a change log.  See https://keepachangelog.com/ for some
-    useful guidelines.
+.. code:: bash
 
+    git push --set-upstream origin chore/release/vMAJOR.MINOR.PATCH
 
-2. Create a New Tag
+Open the upstream repository in GitHub, create a pull request and merge
+the branch into ``main`` when all tests passed successfully.
+
+Pull the changes to your remote repository.
+
+.. code:: bash
+
+    git checkout main
+    git pull
+
+
+1. Create a New Tag
 ^^^^^^^^^^^^^^^^^^^
 
-Create a new tag that contains the new MAJOR.MINOR.PATCH version number
-prefixed with a "v":
+On the ``main`` branch, create a new tag that contains the new
+MAJOR.MINOR.PATCH version number prefixed with a "v":
 
 .. code-block:: bash
 
     git checkout main
-    git tag -m "Release Description" vMAJOR.MINOR.PATCH
+    git tag -a vMAJOR.MINOR.PATCH
+
+As tag message enter:
+
+.. code-block:: text
 
-As tag message use the change log of the new release.
+    HPCSS version MAJOR.MINOR.PATCH
 
+    Release notes at https://github.com/andthum/hpc_submit_scripts/releases
 
-3. Push the Tag to the Upstream Repository
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Push the tag to the upstream repository.
 
 .. important::
 
@@ -75,4 +116,16 @@ As tag message use the change log of the new release.
     git push --tags
 
 
+3. Create a New Release
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Open the upstream repository in GitHub and follow the steps outlined in
+the GitHub doc page
+`Creating automatically generated release notes for a new release
+<https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#creating-automatically-generated-release-notes-for-a-new-release>`_.
+When selecting a tag, use the tag you just created in the previous step.
+Carefully check the automatically generated release notes and make
+changes if necessary.
+
+
 .. _semantic versioning: http://semver.org/
diff --git a/docs/source/doc_pages/general/config_file.rst b/docs/source/doc_pages/general/config_file.rst
@@ -38,7 +38,7 @@ built-in :mod:`configparser` Python module.
     Don't use quotation marks in option values unless you explicitly
     want them to be part of the option value.
 
-Differences to the default behaviour of :mod:`configparser`:
+Differences to the default behavior of :mod:`configparser`:
 
     * The only values that are interpreted as booleans are true and
       false. yes/no and on/off are read as strings.
@@ -53,7 +53,7 @@ Config Sections
 Which sections are recognized by which submit script is stated in the
 "Config File" section of each script right below the "Options" section.
 
-Generraly,
+Generally,
 
     * Options in [submit\*] sections are parsed to Python submit
       scripts.
diff --git a/docs/source/doc_pages/general/hpc_terminology.rst b/docs/source/doc_pages/general/hpc_terminology.rst
@@ -95,11 +95,11 @@ Terms that you will probably come across when you perform computations
 on multiple CPUs:
 
 Distributed-Memory System
-    A computer with mutliple processors in which each processor has its
+    A computer with multiple processors in which each processor has its
     own private memory.  Processors cannot access the memory of other
     processors.
 Shared-Memory System
-    A computer with mutliple processors that all share the same memory.
+    A computer with multiple processors that all share the same memory.
 MPI
     The Message Passing Interface (MPI) is a message-passing standard
     that allows multiple processes that run in separate memory spaces to
diff --git a/docs/source/doc_pages/general/installation.rst b/docs/source/doc_pages/general/installation.rst
@@ -50,7 +50,7 @@ or re-download the project repository (if you don't use |Git|).
 After cloning or pulling the repository, you may want to change the
 default settings using a |config_file|.  For example, you may want to
 set the default for the \--mail-user option of sbatch to your mail
-adress.
+address.
 
 
 Development Installation
diff --git a/docs/source/doc_pages/general/sbatch_options.rst b/docs/source/doc_pages/general/sbatch_options.rst
@@ -8,7 +8,7 @@ scripts (additional to the script's own options).  These options will be
 parsed to the |sbatch| command that submits the Slurm job scripts.
 
 This page contains a subset of sbatch options you might consider useful.
-Refer to the `documetation of sbatch
+Refer to the `documentation of sbatch
 <https://slurm.schedmd.com/sbatch.html>`__ for a full list of all
 options.
 
