This is an automated email from the ASF dual-hosted git repository.
tomaz pushed a commit to branch apidocs_improvements
in repository https://gitbox.apache.org/repos/asf/libcloud.git
commit 263e22d9b2e8ad64f4f952b0db0404bc1bfbf133
Author: Tomaz Muraus <to...@tomaz.me>
AuthorDate: Tue Aug 8 22:38:01 2023 +0200
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 3e9c65927..ece3771e1 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 f9e51d44e..ea176d877 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 @@ BASE_DIR = os.path.abspath(BASE_DIR)
# 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_issues_in_changelog(app, docname, source):
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 6b98a8abd..b09da4472 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
