Merge pull request ComplianceAsCode#10928 from VCTLabs/sphinx-apidocs

Sphinx apidocs

.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/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`:

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/'