From 263e22d9b2e8ad64f4f952b0db0404bc1bfbf133 Mon Sep 17 00:00:00 2001 From: Tomaz Muraus Date: Tue, 8 Aug 2023 22:38:01 +0200 Subject: [PATCH 1/4] Move api docs building inside the sphinx config. This seems to be the preferred approach. This way we can can re-use the same tox target for CI and simplify our config. Also update api docs config to use separate files for easier linking and exclude test modules and packages from api docs. --- .github/workflows/main.yml | 2 +- docs/conf.py | 28 ++++++++++++++++++++++++---- tox.ini | 12 ------------ 3 files changed, 25 insertions(+), 17 deletions(-) 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..ea176d877b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,9 +14,11 @@ import os import re import sys +import glob 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. @@ -335,5 +333,27 @@ 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"] + + 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) 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 From cb185f495e2216ac1e8e46e2df9563494463d483 Mon Sep 17 00:00:00 2001 From: Tomaz Muraus Date: Tue, 8 Aug 2023 22:43:05 +0200 Subject: [PATCH 2/4] Remove unused import. --- docs/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index ea176d877b..d3c94288ca 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,6 @@ import sys import glob import datetime -import subprocess from sphinx.ext import apidoc from sphinx.domains.python import PythonDomain From d7f0a8bb17089d361bf01fb6c7d751253e06a9fe Mon Sep 17 00:00:00 2001 From: Tomaz Muraus Date: Tue, 8 Aug 2023 22:46:25 +0200 Subject: [PATCH 3/4] Remove docs/apidocs/ directory if it already exists to ensure we always start with a clean environment when building apidocs. --- docs/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index d3c94288ca..9e6f4cba93 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,6 +15,7 @@ import re import sys import glob +import shutil import datetime from sphinx.ext import apidoc @@ -338,6 +339,10 @@ def run_apidoc(_): # 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 From 6b23b7bd58ecf5410f95313a1f6a40dc3d44329c Mon Sep 17 00:00:00 2001 From: Tomaz Muraus Date: Tue, 8 Aug 2023 23:00:11 +0200 Subject: [PATCH 4/4] Add :orphan: tag to apidocs/modules.rst to avoid warnings during the docs build. --- docs/conf.py | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 9e6f4cba93..0232e4415f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -303,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") @@ -361,3 +372,4 @@ def run_apidoc(_): 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)