Add Sphinx Documentation (#6)

* Create the infrastructure for generating the Sphinx
  documentation.
* Add a job to the CI pipeline to build the documentation.
* Add a documentation badge to the README.md.
* Fix Sphinx warnings/errors.

.gitlab-ci.yml

@@ -3,19 +3,11 @@
 # https://docs.gitlab.com/ee/ci/yaml/.
 
 
-#image: alpine:latest
-
-
-#variables:
-  #HTTP_PROXY: http://wwwproxy.sandia.gov:80
-  #HTTPS_PROXY: http://wwwproxy.sandia.gov:80
-  #NO_PROXY: 127.0.0.1,localhost,.sandia.gov,/var/run/docker.sock
-
-
 # Set up a global cache to pass information across stages.
 cache: &global_cache
   key: "${CI_COMMIT_REF_SLUG}_${CI_COMMIT_SHORT_SHA}"
   paths:
+    - doc/html/
     - tests/htmlcov/
     - venv-clean-python/
   policy: pull-push
@@ -70,9 +62,14 @@ Install Requirements:
     <<: *global_cache
     when: on_success
   script:
+
+    # Activate the virtual environment.
     - source venv-clean-python/bin/activate
 
-    # Remove shelllogger if it's been installed.
+    # Ensure `pip` is up-to-date.
+    - python3 -m pip install --upgrade pip
+
+    # Remove `shelllogger` if it's been installed.
     - python3 -m pip uninstall -y shelllogger
 
     # Install required packages.
@@ -100,6 +97,8 @@ pytest:
       tests/
   coverage: '/TOTAL\s*[0-9]*\s*[0-9]*\s*[0-9]*\s*[0-9]*\s*(\d+%)/'
   artifacts:
+    paths:
+      - tests/htmlcov
     reports:
       cobertura: tests/coverage.xml
       junit: tests/coverage.xml
@@ -145,10 +144,25 @@ Install Package:
     - python3 -m pip install .
 
 
-# Publish coverage data (if on the main branch).
+# Generate the documentation.
+Sphinx:
+  stage: documentation
+  needs: ["Install Requirements", "Install Package"]
+  timeout: 5m
+  cache:
+    <<: *global_cache
+  script:
+    - cd doc
+    - bash make_html_docs.sh
+  artifacts:
+    paths:
+      - doc/html
+
+
+# Publish coverage data and documentation (if on the main branch).
 Pages:
   stage: publish
-  needs: ["pytest"]
+  needs: ["pytest", "Sphinx"]
   timeout: 5m
   cache:
     <<: *global_cache
@@ -158,6 +172,7 @@ Pages:
   script:
     - mkdir -p public
     - mv tests/htmlcov public/.
+    - mv doc/html/* public/.
   artifacts:
     paths:
       - public

README.md

@@ -1,5 +1,6 @@
 [![pipeline status](https://internal.gitlab.server/ShellLogger/ShellLogger/badges/master/pipeline.svg)](https://internal.gitlab.server/ShellLogger/ShellLogger/pipelines)
-[![coverage report](https://internal.gitlab.server/ShellLogger/ShellLogger/badges/master/coverage.svg)](http://10.202.36.47:8080/ShellLogger/coverage/index.html)
+[![coverage report](https://internal.gitlab.server/ShellLogger/ShellLogger/badges/master/coverage.svg)](http://shelllogger-ci.internal.gitlab.pages/ShellLogger/htmlcov)
+[![documentation](https://img.shields.io/badge/docs-latest-green.svg)](http://shelllogger-ci.internal.gitlab.pages/ShellLogger)
 
 # ShellLogger
 

doc/.gitignore

@@ -0,0 +1 @@
+html

doc/make_html_docs.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+# Remove existing documentation to ensure we build from scratch.
+if [ -e html ]; then
+  rm -rf html
+fi
+
+# Build the Sphinx documentation for `ShellLogger`.
+sphinx-build -b html source/ html/ -W

doc/source/ShellLogger.rst

@@ -0,0 +1,5 @@
+ShellLogger Class Reference
+===========================
+
+.. autoclass:: shelllogger.ShellLogger
+   :noindex:

doc/source/classes.rst

@@ -0,0 +1,77 @@
+Helper Classes
+==============
+
+The following are a number of helper classes used by :class:`ShellLogger`.
+
+JSON Serialization
+------------------
+
+.. autoclass:: shelllogger.ShellLoggerDecoder
+   :noindex:
+
+.. todo::
+
+   Figure out why the documentation below is pulling in the docstring for the
+   base class as well.
+
+.. autoclass:: shelllogger.ShellLoggerEncoder
+   :noindex:
+
+Shell
+-----
+
+.. autoclass:: shelllogger.classes.Shell
+   :noindex:
+
+Trace
+-----
+
+.. autoclass:: shelllogger.classes.Trace
+   :noindex:
+
+.. automethod:: shelllogger.classes::trace_collector
+   :noindex:
+
+Strace
+~~~~~~
+
+.. autoclass:: shelllogger.ShellLogger.Strace
+   :noindex:
+
+Ltrace
+~~~~~~
+
+.. autoclass:: shelllogger.ShellLogger.Ltrace
+   :noindex:
+
+StatsCollector
+--------------
+
+.. autoclass:: shelllogger.classes.StatsCollector
+   :noindex:
+
+.. automethod:: shelllogger.classes::stats_collectors
+   :noindex:
+
+DiskStatsCollector
+~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: shelllogger.ShellLogger.DiskStatsCollector
+   :noindex:
+
+CPUStatsCollector
+~~~~~~~~~~~~~~~~~
+
+.. autoclass:: shelllogger.ShellLogger.CPUStatsCollector
+   :noindex:
+
+MemoryStatsCollector
+~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: shelllogger.ShellLogger.MemoryStatsCollector
+   :noindex:
+
+AbstractMethod
+--------------
+.. autoexception:: shelllogger.classes.AbstractMethod
+   :noindex:

doc/source/conf.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+from pathlib import Path
+import sys
+
+sys.path.append(str(Path.cwd().parent.parent.resolve() / "src"))
+
+# -- Project information -----------------------------------------------------
+
+project = "ShellLogger"
+copyright = "2021, Sandia National Laboratories"
+author = "Josh Braun, David Collins, Jason M. Gates"
+version = "1.0.0"
+release = version
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named `sphinx.ext.*`) or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinxarg.ext",
+    "sphinx_rtd_theme",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# -- AutoDoc Configuration ---------------------------------------------------
+
+autodoc_default_options = {
+    "show-inheritance": True,
+    "members": True,
+    "undoc-members": True
+}
+autoclass_content = "both"
+autodoc_preserve_defaults = True
+autodoc_inherit_docstrings = False
+todo_include_todos = True

doc/source/index.rst

@@ -0,0 +1,86 @@
+shelllogger
+===========
+
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+   :caption: Contents
+
+   ShellLogger
+   classes
+   util
+   todo
+
+The ``shelllogger`` module allows you to interact with the shell, while logging
+various metadata, statistics, and trace information.  Any time you're tempted
+to write your own wrapper around things like :class:`subprocess.Popen` or
+:func:`subprocess.run`, consider using :func:`ShellLogger.log` instead.  The
+following talk from the `US-RSE Virtual Workshop 2021
+<https://us-rse.org/virtual-workshop-2021/>`_ illustrates ``shelllogger`` 's
+functionality.
+
+.. raw:: html
+
+    <div style="position: relative;
+                padding-bottom: 56.25%;
+                height: 0;
+                overflow: hidden;
+                max-width: 100%;
+                height: auto;">
+        <iframe src="https://www.youtube.com/embed/P32RYY_2V7w?start=5985"
+                frameborder="0"
+                allowfullscreen
+                style="position: absolute;
+                       top: 0;
+                       left: 0;
+                       width: 100%;
+                       height: 100%;
+                       padding: 10px;">
+        </iframe>
+    </div>
+
+Where to Get shelllogger
+------------------------
+
+The source repository for this module can be found `here
+<https://internal.gitlab.server/ShellLogger/ShellLogger>`_.  See the project's
+`README.md
+<https://internal.gitlab.server/ShellLogger/ShellLogger/-/blob/master/README.md>`_
+for details on how to clone, install, and otherwise interact with the project.
+
+Using shelllogger
+-----------------
+
+At a high-level, :func:`ShellLogger.log` allows you to execute commands, given
+as strings, in the shell.  When a command is executed, :class:`ShellLogger`
+will also collect the following information:
+
+* The command run
+* A description of the command, or why it was run
+* ``stdout`` and ``stderr``
+* Environment variables
+* Working directory
+* Hostname
+* User and group
+* Umask
+* Return code
+* Ulimit
+* Command start/stop time and duration
+
+It can also optionally collect:
+
+* Resource usage (CPU, memory, disk)
+* Trace information (``strace``, ``ltrace``)
+
+These data are collected in a "log book".  When you call
+:func:`ShellLogger.finalize`, the contents of the log book are written to a
+HTML log file.
+
+Example
+^^^^^^^
+
+.. todo::
+
+   Insert simplest example here, and link to other examples in the repo.
+
+For more detailed usage information, see the :doc:`ShellLogger`.

doc/source/todo.rst

@@ -0,0 +1,9 @@
+To-Do List
+==========
+
+.. |grin| unicode:: U+1F601 .. GRINNING FACE WITH SMILING EYES EMOJI
+
+The following are items that need to be addressed in our documentation.  If
+there's nothing below, then we've already tackled all our to-do items |grin|
+
+.. todolist::

doc/source/util.rst

@@ -0,0 +1,8 @@
+Utilities
+=========
+
+The following are a number of utility functions used to generate the HTML log
+file produced by :class:`ShellLogger`.
+
+.. automodule:: shelllogger.util
+   :noindex:

src/shelllogger/ShellLogger.py

@@ -549,7 +549,7 @@ def log(
         Execute a command, and log the corresponding information.
 
         Parameters:
-            msg:  A message to be recorded with the command. This could
+            msg:  A message to be recorded with the command.  This could
                 be documentation of what your command is doing and why.
             cmd:  The shell command to be executed.
             cwd:  Where to execute the command.

src/shelllogger/classes.py

@@ -246,7 +246,7 @@ def tee(
             The ``stdout`` and ``stderr`` as strings.
 
         Todo:
-          * Replace **kwargs with function arguments.
+          * Replace ``**kwargs`` with function arguments.
         """
         sys_stdout = None if kwargs.get("quiet_stdout") else sys.stdout
         sys_stderr = None if kwargs.get("quiet_stderr") else sys.stderr
@@ -331,7 +331,7 @@ def auxiliary_command(
         Todo:
           * Rip out Windows support.
           * Maybe combine this with :func:`run` with extra flags.
-          * Replace **kwargs with function arguments.
+          * Replace ``**kwargs`` with function arguments.
 
         Returns:
             The ``stdout`` and ``stderr`` of the command run.