From 03948b70a72d521ba7fef388c584ce995120188c Mon Sep 17 00:00:00 2001
From: Stephen L Arnold <sarnold@vctlabs.com>
Date: Thu, 31 Aug 2023 19:06:55 -0700
Subject: [PATCH 1/2] 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 <sarnold@vctlabs.com>
---
 .gitignore            |  8 ++++++++
 docs/conf.py          | 11 +++++++++++
 docs/index.rst        |  8 ++++++++
 docs/requirements.txt |  3 +++
 tox.ini               | 44 +++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 74 insertions(+)
 create mode 100644 tox.ini

diff --git a/.gitignore b/.gitignore
index 0a886ce139a..98cefe31906 100644
--- a/.gitignore
+++ b/.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
diff --git a/docs/conf.py b/docs/conf.py
index 7a288e08f6e..542abde9ad7 100644
--- a/docs/conf.py
+++ b/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']
 
diff --git a/docs/index.rst b/docs/index.rst
index 40277fc5bab..c92be773bf5 100644
--- a/docs/index.rst
+++ b/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:
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 81fde387aff..a7721aedcb8 100644
--- a/docs/requirements.txt
+++ b/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
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 00000000000..32f58c29a6c
--- /dev/null
+++ b/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/'

From e275d0dfae03c23ab6f6ed876245a8bee04b8d49 Mon Sep 17 00:00:00 2001
From: Stephen L Arnold <sarnold@vctlabs.com>
Date: Wed, 20 Sep 2023 16:07:18 -0700
Subject: [PATCH 2/2] Update developer page with tox method for building sphinx
 docs

* changes are in 02_building_complianceascode.md

Signed-off-by: Stephen L Arnold <sarnold@vctlabs.com>
---
 .../developer/02_building_complianceascode.md | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/manual/developer/02_building_complianceascode.md b/docs/manual/developer/02_building_complianceascode.md
index 3f67af4ab7b..38fd48b3489 100644
--- a/docs/manual/developer/02_building_complianceascode.md
+++ b/docs/manual/developer/02_building_complianceascode.md
@@ -159,6 +159,26 @@ apt-get install ninja-build
 
 ### Sphinx packages (Developer Documentation)
 
+Building docs can be done via tox file or manually.  Note that tox creates a
+virtual environment to handle all dependencies defined in the docs requirements
+file.
+
+#### Using the tox file
+
+```bash
+# Fedora/RHEL
+yum install tox
+
+# Ubuntu/Debian
+apt-get install tox
+```
+
+```bash
+tox -e docs
+```
+
+#### Manual method
+
 Install Sphinx packages if you want to generate HTML Documentation, from source directory run:
 
 ```bash
@@ -173,6 +193,10 @@ apt-get install python3-sphinx
 pip install -r docs/requirements.txt
 ```
 
+```bash
+make -C docs html
+```
+
 ### Pandas (SRG Export HTML)
 
 Install `pandas` if you want to run `utils/create_srg_export.py`: