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/manual/developer/02_building_complianceascode.md b/docs/manual/developer/02_building_complianceascode.md index e8f009300c7..b970d974648 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`: 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/'