Fix Python docs for historical versions (#3452)

.azure-pipelines-gh-pages.yml

@@ -23,7 +23,7 @@ jobs:
           git checkout -b main $(git rev-parse HEAD)
         displayName: Prepare repo
 
-      # Used to generate setup.py
+      # Used to generate version.py
       - template: .azure-pipelines-templates/cmake.yml
         parameters:
           cmake_args: ""
@@ -35,6 +35,7 @@ jobs:
           pip install wheel
           pip install -U -r doc/requirements.txt
           pip install -U -e ./python
+          pip install -U -r doc/historical_ccf_requirements.txt
           sphinx-multiversion doc build/html
         displayName: Sphinx
 

doc/conf.py

@@ -22,8 +22,6 @@ import pathlib
 
 from docutils import nodes
 
-sys.path.insert(0, os.path.abspath("../python"))
-
 
 # -- Project information -----------------------------------------------------
 
@@ -213,6 +211,7 @@ for arg in sys.argv:
     if "smv_current_version=" in arg:
         docs_version = arg.split("=")[1]
 
+
 # :ccf_repo: directive can be used to create a versioned link to GitHub repo
 extlinks = {
     "ccf_repo": (
@@ -333,10 +332,10 @@ def typedoc_role(
 def config_inited(app, config):
     # anything that needs to access app.config goes here
 
-    srcdir = pathlib.Path(app.srcdir)
+    doc_dir = pathlib.Path(app.srcdir)
     outdir = pathlib.Path(app.outdir)
 
-    js_pkg_dir = srcdir / ".." / "js" / "ccf-app"
+    js_pkg_dir = doc_dir / ".." / "js" / "ccf-app"
     js_docs_dir = outdir / "js" / "ccf-app"
     if js_pkg_dir.exists():
         # make versions.json from sphinx-multiversion available
@@ -384,9 +383,14 @@ def config_inited(app, config):
 def setup(app):
     app.connect("config-inited", config_inited)
 
-    srcdir = pathlib.Path(app.srcdir)
+    doc_dir = pathlib.Path(app.srcdir)  # CCF/doc/
+    root_dir = os.path.abspath(doc_dir / "..")  # CCF/
+
+    # import ccf python package to generate docs for this version
+    python_path = os.path.abspath(doc_dir / "../python")
+    sys.path.insert(0, python_path)
 
     # doxygen
-    breathe_projects["CCF"] = str(srcdir / breathe_projects["CCF"])
+    breathe_projects["CCF"] = str(doc_dir / breathe_projects["CCF"])
     if not os.environ.get("SKIP_DOXYGEN"):
-        subprocess.run(["doxygen"], cwd=srcdir / "..", check=True)
+        subprocess.run(["doxygen"], cwd=root_dir, check=True)

doc/historical_ccf_requirements.txt

@@ -0,0 +1,4 @@
+# Only used to build documentation for historical versions
+requests_http_signature
+websocket
+httpx