Update filter tree logic, versioned, and aggregate

Always hide other toctrees when on a page included on a toctree.
Squash toctrees without title with the previous toctree
Rework versioned variables, simplify the requirements and allow to be
deployed directly on GitHub multiple versions.
Update symbolic aggregate.

Signed-off-by: Jorge Marques <[email protected]>

.github/workflows/build-doc.yml

@@ -21,15 +21,41 @@ jobs:
 
     - name: Build doc
       working-directory: docs
-      run: |
-        make html SPHINXOPTS='-W --keep-going'
+      run: >
+        ADOC_DOC_VERSION=${{ github.ref_name }}
+        make html SPHINXOPTS='-W --keep-going' ;
+        rm -rf _build/html/_sources
 
     - name: Store the generated doc
       uses: actions/upload-artifact@v4
       with:
         name: html
         path: docs/_build/html
 
+    - name: Check if new tag
+      run: |
+        tag=v$(sed -n 's/^__version__ = "\(.*\)"/\1/p' adi_doctools/__init__.py)
+        git fetch --tags
+        if ! [ $(git tag -l "$tag") ] ; then
+          echo "new_tag=1" >> "$GITHUB_ENV"
+        fi
+
+    - name: Build tagged doc
+      if: ${{ env.new_tag == '1' }}
+      working-directory: docs
+      run: >
+        ADOC_TARGET_DEPTH=1
+        ADOC_DOC_VERSION=$tag
+        make clean html SPHINXOPTS='-W --keep-going' ;
+        rm -rf _build/html/_sources
+
+    - name: Store the generated tagged doc
+      if: ${{ env.new_tag == '1' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-tagged
+        path: docs/_build/html
+
   build-doc-min:
     runs-on: ubuntu-20.04
 
@@ -53,6 +79,7 @@ jobs:
       working-directory: docs
       run: |
         make html SPHINXOPTS='-W --keep-going'
+        rm -rf _build/html/_sources
 
     - name: Store the generated doc
       uses: actions/upload-artifact@v4

.github/workflows/deploy.yml

@@ -13,10 +13,10 @@ jobs:
 
     - name: Get head tag, if it is new and others vars
       run: |
-        tag=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' adi_doctools/__init__.py)
+        tag=v$(sed -n 's/^__version__ = "\(.*\)"/\1/p' adi_doctools/__init__.py)
         echo "tag=$tag" >> "$GITHUB_ENV"
         git fetch --tags
-        if ! [ $(git tag -l "v$tag") ] ; then
+        if ! [ $(git tag -l "$tag") ] ; then
           echo "new_tag=1" >> "$GITHUB_ENV"
         fi
 
@@ -64,8 +64,8 @@ jobs:
     - name: Create new tag
       if: ${{ env.new_tag == '1' }}
       run: |
-         git tag v$tag
-         git push origin v$tag
+         git tag $tag
+         git push origin $tag
 
     - name: Create tag release and upload asset
       if: ${{ env.new_tag == '1' }}
@@ -144,28 +144,41 @@ jobs:
         (
           git fetch origin gh-pages ;
           git checkout -b gh-pages origin/gh-pages ;
-          git rm -r . --quiet || true
+          DOC_BUILDS=$(find . -mindepth 2 -name objects.inv -exec sh -c 'dirname {}' ';') ;
+          git rm -r . --quiet || true ;
+          printf "Detected doc builds: $DOC_BUILDS" ;
+          if ! [ -z "$DOC_BUILDS" ]; then
+            git checkout @ -- $DOC_BUILDS ;
+          fi ;
+          if [[ "$new_tag" == "1" ]]; then
+            git rm -r $tag --quiet || true ;
+          fi ;
         ) || (
           git checkout --orphan gh-pages ;
           git reset --hard ;
-          git commit -m "empty" --allow-empty
+          git commit -m "initial commit" --allow-empty
         )
 
     - uses: actions/download-artifact@v4
       with:
         name: html
 
-    - name: Patch doc build
-      run: |
-        rm -r _sources
-        touch .nojekyll
+    - uses: actions/download-artifact@v4
+      if: ${{ env.new_tag == '1' }}
+      with:
+        name: html-tagged
+        path: ${{ env.tag }}
 
-    - name: Commit gh-pages
+    - name: Generate aux files
+      run: >
+        touch .nojekyll ;
+        find . -name objects.inv -exec sh -c 'dirname {}' ';' |
+        cut -c 3- |
+        jq --raw-input . |
+        jq --slurp . > tags.json
+
+    - name: Commit and push to gh-pages
       run: |
         git add . >> /dev/null
         git commit -m "deploy: ${GITHUB_SHA}" --allow-empty
-
-
-    - name: Push to gh-pages
-      run: |
         git push origin gh-pages:gh-pages

adi_doctools/__init__.py

@@ -1,6 +1,8 @@
 from os import path, getenv
+from packaging.version import Version
 
 from sphinx.util import logging
+from sphinx.util.osutil import SEP
 
 from .theme import (navigation_tree, get_pygments_theme,
                     write_pygments_css, wrap_elements)
@@ -9,7 +11,7 @@
 from .role import setup as role_setup
 from .lut import get_lut
 
-__version__ = "0.3.37"
+__version__ = "0.3.38"
 
 logger = logging.getLogger(__name__)
 
@@ -31,7 +33,6 @@ def get_navigation_tree(app, context, pagename):
     from sphinx import __version__ as __sphinx_version__
 
     if Version(__sphinx_version__) < Version('7.2.0'):
-        from sphinx.util.osutil import SEP
         from urllib.parse import quote
 
         url = quote(pagename)
@@ -47,15 +48,21 @@ def html_page_context(app, pagename, templatename, context, doctree):
      context["repotoc_tree"],
      context["repotoc_current_name"],
      context["repotoc_current"]) = ret
+    context["global_root"] = path.join(context["content_root"],
+                                       app.env.target_depth) + SEP
 
 
 def config_inited(app, config):
     app.lut = get_lut()
 
-    doc_version = getenv("ADOC_DOC_VERSION", default=None)
-    if 'version' not in config:
+    doc_version = getenv("ADOC_DOC_VERSION", default="")
+    if 'version' not in config or config.version == "":
+        try:
+            doc_version = str(Version(doc_version))
+        except Exception as err:
+            pass
         config.version = doc_version
-    elif doc_version is not None:
+    elif doc_version != "":
         logger.warn("ADOC_DOC_VERSION set but ignored due to "
                     "conf.py version entry")
 
@@ -73,7 +80,14 @@ def builder_inited(app):
             get_pygments_theme(app)
         else:
             app.add_css_file("third-party.css", priority=500, defer="")
-
+        # Setup meta tag with target depth
+        target_depth = getenv("ADOC_TARGET_DEPTH", default=0)
+        try:
+            target_depth_ = int(target_depth)
+            app.env.target_depth = path.join('..', *[".."]*target_depth_)
+        except Exception as err:
+            logger.warn(f"ADOC_TARGET_DEPTH '{target_depth}' is not an int, ignored")
+            app.env.target_depth = '..'
 
 def build_finished(app, exc):
     """

adi_doctools/cli/aggregate.py

@@ -1,4 +1,5 @@
 from typing import Tuple, List
+from sphinx.util.osutil import SEP
 
 import os
 import click
@@ -11,16 +12,14 @@
 no_parallel = True
 lut = get_lut()
 repos = lut['repos']
-remote = lut['remote']
-
 
 
 class pr:
     @staticmethod
-    def popen(cmd, p: List, cwd: [str, None] = None):
+    def popen(cmd, p: List, cwd: [str, None] = None, env = None):
         global dry_run, no_parallel
         if not dry_run:
-            p__ = subprocess.Popen(cmd, cwd=cwd)
+            p__ = subprocess.Popen(cmd, cwd=cwd, env=env)
             p__.wait() if no_parallel else p.append(p__)
         elif cwd is not None:
             click.echo(f"cd {cwd}; {' '.join(cmd)}")
@@ -178,20 +177,26 @@ def gen_symbolic_doc(repo_dir):
     p = []
     for r in repos:
         cwd = os.path.join(repo_dir, f"{r}/{repos[r]['doc_folder']}")
+        click.echo(f"Starting sphinx for {r}")
         mk.append(get_sphinx_dirs(cwd))
         if mk[-1][0]:
             continue
-        pr.popen(['make', 'html'], p, cwd)
+
+        env = os.environ.copy()
+        env["ADOC_INTERREF_URI"] = os.path.abspath(os.path.join(os.getcwd(), "html")) + SEP
+        pr.popen(['make', 'html'], p, cwd, env=env)
     pr.wait(p)
 
     d_ = os.path.abspath(os.path.join(repo_dir, os.pardir))
+
     out = os.path.join(d_, 'html')
+    pr.run(f"rm -r {out}")
     pr.mkdir(out)
     for r, m in zip(repos, mk):
         if m[0]:
             continue
         d_ = os.path.join(out, r)
-        pr.popen(['ln', '-sf', m[1], d_], p)
+        pr.popen(['cp', '-r', m[1], d_], p)
     pr.wait(p)
 
 
@@ -339,13 +344,16 @@ def aggregate(directory, symbolic, extra, no_parallel_, dry_run_, open_):
     """
     Creates an aggregated documentation out of every repo documentation,
     by default, will conjoin/patch each into a single Sphinx build.
+    To resolve inter-repo-references in symbolic mode, run twice.
     """
     global dry_run, no_parallel
     no_parallel = no_parallel_
     dry_run = dry_run_
     directory = os.path.abspath(directory)
-    click.echo("This feature is currently disabled")
-    return
+
+    if not symbolic:
+        click.echo("Currently, monolithic output is disabled")
+        return
 
     if not extra:
         click.echo("Extra features disabled, use --extra to enable.")
@@ -357,18 +365,11 @@ def aggregate(directory, symbolic, extra, no_parallel_, dry_run_, open_):
         if not os.path.isdir(repos_dir):
             pr.mkdir(repos_dir)
 
-    d = 'html' if symbolic else 'html_mono'
-    d__ = os.path.join(directory, d)
-    if os.path.isdir(d__):
-        pr.run(f"rm -r {d__}")
-
     p = []
-    for r in lut:
-        r__ = remote if 'remote' not in repos[r] else repos[r]['remote']
-        r_ = r__.format(r)
+    for r in repos:
         cwd = os.path.join(repos_dir, r)
         if not os.path.isdir(cwd):
-            git_cmd = ["git", "clone", r_, "--depth=1", "-b",
+            git_cmd = ["git", "clone", lut['remote'].format(r), "--depth=1", "-b",
                        repos[r]['branch'], '--', cwd]
             pr.popen(git_cmd, p)
         else:

adi_doctools/lut.py

@@ -11,7 +11,6 @@ class Repo(TypedDict):
     doc_folder: str
     name: str
     branch: str
-    release_format: str
     visibility: str
     topic: Optional[Dict[str, str]]
     extra: Optional[Tuple[str, List[str], bool]]
@@ -30,7 +29,6 @@ class LUT(TypedDict):
         doc_folder='docs',
         name='System Level',
         branch='main',
-        release_format='const:latest',
         visibility='public',
         topic={
             'eval': 'Evaluation Boards',
@@ -45,42 +43,36 @@ class LUT(TypedDict):
         ),
         name='HDL',
         branch='main',
-        release_format='halves',
-        visibility='public'
-    ),
-    'no-OS': Repo(
-        doc_folder='doc/sphinx/source',
-        name='no-OS',
-        branch='main',
-        release_format='const:latest_commit',
         visibility='public'
     ),
     'pyadi-iio': Repo(
         doc_folder='doc',
         name='Hardware Python Interfaces',
         branch='main',
-        release_format='semantic',
+        visibility='public'
+    ),
+    'no-OS': Repo(
+        doc_folder='doc/sphinx/source',
+        name='no-OS',
+        branch='main',
         visibility='public'
     ),
     'precision-converters-firmware': Repo(
         doc_folder='doc/sphinx',
         name='Precision Converters Firmware',
         branch='main',
-        release_format='const:latest',
         visibility='public'
     ),
-    'doctools': Repo(
+    'PrecisionToolbox': Repo(
         doc_folder='docs',
-        name='Doctools',
+        name='Precision Toolbox',
         branch='main',
-        release_format='semantic',
         visibility='public'
     ),
-    'PrecisionToolbox': Repo(
+    'doctools': Repo(
         doc_folder='docs',
-        name='Precision Toolbox',
+        name='Doctools',
         branch='main',
-        release_format='const:latest',
         visibility='public'
     ),
 }