Add auto-generated docs, Read the Docs support, and GitHub Actions wo…

…rkflow.

.github/workflows/lint-test-cover-docs.yml

@@ -0,0 +1,35 @@
+name: lint-test-cover-docs
+on:
+  push
+jobs:
+  lint_test_cover_docs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
+    name: "Python ${{ matrix.python-version }}"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Python.
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: x64
+      - name: Lint and test module.
+        run: |
+          pip install -U .[lint,test]
+          python -m pylint richreports # Check against linting rules.
+          python -m pytest # Run tests.
+          python src/richreports/richreports.py -v # Run tests via execution.
+      - name: Publish coverage results.
+        run: |
+          pip install -U .[coveralls]
+          python -m coveralls --service=github # Submit to coveralls.
+        if: matrix.python-version == '3.11'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+      - name: Test auto-generation of documentation.
+        run: |
+          pip install -U .[docs]
+          cd docs && sphinx-apidoc -f -E --templatedir=_templates -o _source .. && make html && cd ..

.readthedocs.yaml

@@ -0,0 +1,19 @@
+version: 2
+
+sphinx:
+   configuration: docs/conf.py
+
+formats:
+  - pdf
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"

README.rst

@@ -4,12 +4,20 @@ richreports
 
 Library that supports the construction of human-readable, interactive static analysis reports that consist of decorated concrete syntax representations of programs.
 
-|pypi| |coveralls|
+|pypi| |readthedocs| |actions| |coveralls|
 
 .. |pypi| image:: https://badge.fury.io/py/richreports.svg#
    :target: https://badge.fury.io/py/richreports
    :alt: PyPI version and link.
 
+.. |readthedocs| image:: https://readthedocs.org/projects/richreports/badge/?version=latest
+   :target: https://richreports.readthedocs.io/en/latest/?badge=latest
+   :alt: Read the Docs documentation status.
+
+.. |actions| image:: https://github.com/reity/richreports-py/workflows/lint-test-cover-docs/badge.svg#
+   :target: https://github.com/reity/richreports-py/actions/workflows/lint-test-cover-docs.yml
+   :alt: GitHub Actions status.
+
 .. |coveralls| image:: https://coveralls.io/repos/github/reity/richreports-py/badge.svg?branch=main
    :target: https://coveralls.io/github/reity/richreports-py?branch=main
    :alt: Coveralls test coverage summary.
@@ -31,7 +39,10 @@ The library can be imported in the usual way:
 Examples
 ^^^^^^^^
 
-This library supports the enrichment of concrete syntax strings with delimiters. A ``report`` instance can be created from a concrete string and then enriched:
+.. |report| replace:: ``report``
+.. _report: https://richreports.readthedocs.io/en/0.1.0/_source/richreports.html#richreports.richreports.report
+
+This library supports the enrichment of concrete syntax strings with delimiters. A |report|_ instance can be created from a concrete string and then enriched:
 
 .. code-block:: python
 
@@ -64,11 +75,21 @@ This makes it possible to succinctly build up reports that correspond to structu
 
 Development
 -----------
-All installation and development dependencies are fully specified in ``pyproject.toml``. The ``project.optional-dependencies`` object is used to `specify optional requirements <https://peps.python.org/pep-0621>`__ for various development tasks. This makes it possible to specify additional options (such as ``test``, ``lint``, and so on) when performing installation using `pip <https://pypi.org/project/pip>`__:
+All installation and development dependencies are fully specified in ``pyproject.toml``. The ``project.optional-dependencies`` object is used to `specify optional requirements <https://peps.python.org/pep-0621>`__ for various development tasks. This makes it possible to specify additional options (such as ``docs``, ``lint``, and so on) when performing installation using `pip <https://pypi.org/project/pip>`__:
+
+.. code-block:: bash
+
+    python -m pip install .[docs,lint]
+
+Documentation
+^^^^^^^^^^^^^
+The documentation can be generated automatically from the source files using `Sphinx <https://www.sphinx-doc.org>`__:
 
 .. code-block:: bash
 
-    python -m pip install .[test,lint]
+    python -m pip install .[docs]
+    cd docs
+    sphinx-apidoc -f -E --templatedir=_templates -o _source .. && make html
 
 Testing and Conventions
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -94,7 +115,7 @@ Style conventions are enforced using `Pylint <https://pylint.readthedocs.io>`__:
 
 Contributions
 ^^^^^^^^^^^^^
-In order to contribute to the source code, open an issue or submit a pull request on the `GitHub page <https://github.com/reity/richreports-py>`__ for this library.
+In order to contribute to the source code, open an issue or submit a pull request on the `GitHub page <https://github.com/lapets/richreports>`__ for this library.
 
 Versioning
 ^^^^^^^^^^
@@ -108,7 +129,7 @@ This library can be published as a `package on PyPI <https://pypi.org/project/ri
 
     python -m pip install .[publish]
 
-Ensure that the correct version number appears in ``pyproject.toml``. Create and push a tag for this version (replacing ``?.?.?`` with the version number):
+Ensure that the correct version number appears in ``pyproject.toml``, and that any links in this README document to the Read the Docs documentation of this package (or its dependencies) have appropriate version numbers. Also ensure that the Read the Docs project for this library has an `automation rule <https://docs.readthedocs.io/en/stable/automation-rules.html>`__ that activates and sets as the default all tagged versions. Create and push a tag for this version (replacing ``?.?.?`` with the version number):
 
 .. code-block:: bash
 

docs/Makefile

@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	rm _source/modules.rst
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_source/richreports.rst

@@ -0,0 +1,8 @@
+richreports module
+==================
+
+
+.. automodule:: richreports.richreports
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/_templates/module.rst_t

@@ -0,0 +1,9 @@
+{%- if show_headings %}
+{{- [basename, "module"] | join(' ') | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
+

docs/_templates/package.rst_t

@@ -0,0 +1,36 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{{- [pkgname, "module"] | join(" ") | e | heading }}
+
+{%- if subpackages %}
+Subpackages
+-----------
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}

docs/_templates/toc.rst_t

@@ -0,0 +1,8 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+

docs/conf.py

@@ -0,0 +1,86 @@
+# 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:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- 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.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../src')) # Prioritize local module copy.
+
+
+# -- Project information -----------------------------------------------------
+
+# The name and version are retrieved from ``pyproject.toml`` in the root
+# directory.
+import toml
+with open('../pyproject.toml') as pyproject_file:
+    pyproject_data = toml.load(pyproject_file)
+project = pyproject_data['project']['name']
+version = pyproject_data['project']['version']
+release = version
+
+# The copyright year and holder information is retrieved from the
+# ``LICENSE`` file.
+import re
+with open('../LICENSE', 'r') as license_file:
+    license_string = license_file.read().split('Copyright (c) ')[1]
+year = license_string[:4]
+author = license_string[5:].split('\n')[0]
+copyright = year + ', ' + re.sub(r"\.$", "", author) # Period already in HTML.
+
+
+# -- 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.doctest',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode'
+]
+
+# 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 = ['_build']
+
+# Options to configure autodoc extension behavior.
+autodoc_member_order = 'bysource'
+autodoc_preserve_defaults = True
+
+# Allow references/links to definitions found in the Python documentation.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}
+
+# Do not display fully qualified names.
+add_module_names = False
+
+
+# -- 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'
+
+# Theme options for Read the Docs.
+html_theme_options = {
+    'display_version': True,
+    'collapse_navigation': True,
+    'navigation_depth': 1,
+    'titles_only': True
+}

docs/index.rst

@@ -0,0 +1,2 @@
+.. include:: ../README.rst
+.. include:: toc.rst

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+del _source\modules.rst
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/toc.rst

@@ -0,0 +1,5 @@
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+
+   _source/richreports

pyproject.toml

@@ -16,8 +16,14 @@ requires-python = ">=3.7"
 
 [project.urls]
 Repository = "https://github.com/reity/richreports-py"
+Documentation = "https://richreports.readthedocs.io"
 
 [project.optional-dependencies]
+docs = [
+    "toml~=0.10.2",
+    "sphinx~=5.0",
+    "sphinx-rtd-theme~=1.1.0"
+]
 test = [
     "pytest~=7.4",
     "pytest-cov~=4.0"
@@ -40,4 +46,4 @@ requires = [
 build-backend = "setuptools.build_meta"
 
 [tool.pytest.ini_options]
-addopts = "--doctest-modules --cov=richreports --cov-report term-missing"
+addopts = "--doctest-modules --ignore=docs --cov=richreports --cov-report term-missing"