add sphinxcontrib-apidoc to docs build, test sphinx with tox file

* this adds highlighted source/links to module references in sphinx docs,
  plus a small tox file for sphinx builds and static linting

Signed-off-by: Stephen L Arnold <[email protected]>

.gitignore

@@ -10,6 +10,14 @@ rpmbuild
 container_build/
 build/
 
+# Ignore docs generated API sources
+docs/api/
+
+# Ignore workflow artifacts
+.tox/
+ext/
+__pycache__/
+
 # Ignore docs tmp directories
 docs/Developer_Guide/tmp
 docs/SCAP_and_STIG_Workshop/tmp

docs/conf.py

@@ -40,12 +40,23 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['myst_parser',
+    'sphinxcontrib.apidoc',
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode',
+    'sphinxcontrib.jinjadomain',
     'sphinxcontrib.autojinja.jinja',
 ]
 
+apidoc_module_dir = '../ssg'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = ['tests', 'build-scripts']
+apidoc_separate_modules = True
+
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
 

docs/index.rst

@@ -60,6 +60,14 @@ ComplianceAsCode/content
 
     modules/*
 
+.. toctree::
+    :maxdepth: 4
+    :glob:
+    :caption: Python SSG Module API Reference
+    :name: SSG API Reference
+
+    api/modules
+
 .. toctree::
     :maxdepth: 2
     :glob:

docs/requirements.txt

@@ -1,5 +1,8 @@
+libvirt-python
+PyGithub
 myst-parser
 sphinx
 sphinx-rtd-theme
+sphinxcontrib-apidoc
 git+https://github.com/sphinx-contrib/napoleon.git#egg=sphinxcontrib-napoleon
 git+https://github.com/ggbecker/sphinxcontrib.jinjadomain.git#egg=sphinxcontrib-jinjadomain

tox.ini

@@ -0,0 +1,44 @@
+[tox]
+envlist = py27,py3{6,7,8,9,10,11},flake8,docs
+skip_missing_interpreters = true
+isolated_build = true
+skipsdist = true
+
+[flake8]
+max-line-length = 99
+
+[testenv]
+skip_install = true
+install_command = pip install {opts} {packages}
+
+[testenv:flake8]
+basepython = python3
+commands =
+    flake8 ssg utils
+deps =
+    flake8
+
+[testenv:docs]
+skip_install=false
+skipsdist=true
+basepython = python3
+allowlist_externals =
+    make
+deps =
+    -r docs/requirements.txt
+commands =
+    make -C docs html
+commands_post =
+    make -C docs linkcheck
+
+[testenv:clean]
+skip_install = true
+allowlist_externals =
+    bash
+
+deps =
+    pip>=21.1
+
+commands =
+    bash -c 'make -C docs/ clean'
+    bash -c 'rm -rf dist/ build/* docs/api/'