diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 3e9c659271..ece3771e1a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -374,7 +374,7 @@ jobs: - name: Build Docs run: | - tox -e docs-ci + tox -e docs - name: Trigger ReadTheDocs build if: ${{ github.ref_name == 'trunk' }} diff --git a/docs/conf.py b/docs/conf.py index f9e51d44ed..0232e4415f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,9 +14,11 @@ import os import re import sys +import glob +import shutil import datetime -import subprocess +from sphinx.ext import apidoc from sphinx.domains.python import PythonDomain BASE_DIR = os.path.dirname(os.path.abspath(__file__)) @@ -25,10 +27,6 @@ # Detect if we are running on read the docs on_rtd = os.environ.get("READTHEDOCS", "").lower() == "true" -if on_rtd: - cmd = "sphinx-apidoc -d 4 -o apidocs/ ../libcloud/" - subprocess.call(cmd, shell=True) - # 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. @@ -305,10 +303,21 @@ ] +def add_orphan_tag_to_apidocs(app, docname, source): + """ + Add :orphan: tag to apidocs/modules.rst file to avoid errors during docs build. + """ + + if docname == "apidocs/modules": + source[0] = ":orphan:" + "\n\n" + source[0] + + # Taken and based from code in the sphinx project (BSD 2.0 license) # https://github.com/sphinx-doc/sphinx/blob/master/doc/conf.py def linkify_issues_in_changelog(app, docname, source): - """Linkify issue references like #123 in changelog to GitHub.""" + """ + Linkify issue references in changelog to GitHub and Jira. + """ if docname == "changelog": changelog_path = os.path.join(BASE_DIR, "../CHANGES.rst") @@ -335,5 +344,32 @@ def linkify_jira_issues(match): source[0] = source[0].replace(".. include:: ../CHANGES.rst", linkified_changelog) +def run_apidoc(_): + # ignore test modules + ignore_paths = glob.glob("../libcloud/test/**/*.py", recursive=True) + # Problematic driver with hundreds of issues + ignore_paths += ["../libcloud/compute/drivers/outscale.py"] + + # Remove existing api docs directory if it exists so we start with a clean environment + apidocs_dir = os.path.abspath(os.path.join(BASE_DIR, "apidocs/")) + shutil.rmtree(apidocs_dir, ignore_errors=True) + + argv = [ + "--force", # Overwrite output files + "--follow-links", # Follow symbolic links + "--module-first", # Put module documentation before submodule + "--separate", + "--maxdepth", + "4", + "-o", + "apidocs", # Output path + "../libcloud", # include path + ] + ignore_paths + + apidoc.main(argv) + + def setup(app): + app.connect("builder-inited", run_apidoc) app.connect("source-read", linkify_issues_in_changelog) + app.connect("source-read", add_orphan_tag_to_apidocs) diff --git a/tox.ini b/tox.ini index 6b98a8abda..b09da44728 100644 --- a/tox.ini +++ b/tox.ini @@ -180,21 +180,9 @@ deps = -r{toxinidir}/requirements-docs.txt changedir = docs commands = rstcheck --report-level warning ../CHANGES.rst - python ../contrib/generate_provider_feature_matrix_table.py - sphinx-apidoc -d 4 ../libcloud/ -o apidocs/ - /bin/bash -c "ls apidocs/modules.rst && (grep orphan apidocs/modules.rst || sed -i '1i :orphan:\n' apidocs/modules.rst) || (exit 0)" - # TODO: Add -W back when we fix all the warnings in docstrings - sphinx-build -j auto -b html -d {envtmpdir}/doctrees . _build/html - -[testenv:docs-ci] -deps = - -r{toxinidir}/requirements-docs.txt -changedir = docs -commands = rstcheck --report-level warning ../README.rst rstcheck --report-level warning ../CHANGES.rst rstcheck --report-level warning ../CONTRIBUTING.rst python ../contrib/generate_provider_feature_matrix_table.py - /bin/bash -c "ls apidocs/modules.rst && (grep orphan apidocs/modules.rst || sed -i '1i :orphan:\n' apidocs/modules.rst) || (exit 0)" # TODO: Add -W back when we fix all the warnings in docstrings sphinx-build -j auto -b html -d {envtmpdir}/doctrees . _build/html