Add new CLI tool to allow custom html/pdf docs generation

.github/workflows/custom-doc.yml

@@ -0,0 +1,33 @@
+on: workflow_call
+jobs:
+  custom-doc:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+
+    - uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist
+
+    - name: Install pip packages
+      run: |
+        pip install $(tail --lines=+2 docs/requirements.txt) --upgrade
+        pip install weasyprint sphinxcontrib.wavedrom matplotlib
+        pip install dist/adi_doctools-*.tar.gz
+
+    - name: Build custom doc
+      working-directory: /tmp
+      run: |
+        adoc custom-doc -d my_pdf --builder pdf --https
+        adoc custom-doc -d my_pdf --builder pdf --https
+
+    - name: Store the generated pdf
+      uses: actions/upload-artifact@v4
+      with:
+        name: custom-pdf
+        path: /tmp/my_pdf/_build/output.pdf

.github/workflows/top-level.yml

@@ -16,10 +16,14 @@ jobs:
     uses: ./.github/workflows/tests.yml
     needs: [build-package]
     secrets: inherit
+  custom-doc:
+    uses: ./.github/workflows/custom-doc.yml
+    needs: [build-package]
+    secrets: inherit
   deploy:
     if: github.ref == 'refs/heads/main'
     uses: ./.github/workflows/deploy.yml
-    needs: [build-doc, tests]
+    needs: [build-doc, tests, custom-doc]
     secrets: inherit
     permissions:
       contents: write

MANIFEST.in

@@ -1,6 +1,7 @@
 include adi_doctools/miscellaneous/*.js
 include adi_doctools/miscellaneous/*.svg
 include adi_doctools/miscellaneous/*.css
+include adi_doctools/theme/cosmic/style/*.css
 include adi_doctools/theme/cosmic/static/*.umd.js
 include adi_doctools/theme/cosmic/static/*.js.map
 include adi_doctools/theme/cosmic/static/*.min.css

adi_doctools/__init__.py

@@ -12,7 +12,7 @@
 from .role.interref import interref_repos_apply
 from .monkeypatch import monkeypatch_figure_numbers
 
-__version__ = "0.3.49"
+__version__ = "0.3.50"
 
 
 def get_navigation_tree(app, context, pagename):
@@ -69,9 +69,7 @@ def config_inited(app, config):
             pass
         config.version = doc_version
     # Parameter to enable PDF output tweaks
-    media_print = getenv("ADOC_MEDIA_PRINT", default="0")
-    media_print = True if media_print == "1" else False
-    config.media_print = media_print
+    config.media_print = True if getenv("ADOC_MEDIA_PRINT") is not None else False
 
 def builder_inited(app):
     if app.builder.format == 'html':
@@ -82,7 +80,7 @@ def builder_inited(app):
         # Add bundled JavaScript if current theme is from this extension.
         if app.env.config.html_theme in theme_names:
             app.add_js_file("app.umd.js", priority=500, defer="")
-            app.config.html_permalinks_icon = "#"
+            app.config.html_permalinks_icon = ""
             get_pygments_theme(app)
         else:
             app.add_css_file("third-party.css", priority=500, defer="")

adi_doctools/cli/__init__.py

@@ -4,6 +4,7 @@
 from .hdl_render import hdl_render
 from .hdl_gen import hdl_gen
 from .aggregate import aggregate
+from .custom_doc import custom_doc
 
 
 @click.group()
@@ -18,7 +19,8 @@ def entry_point():
     author_mode,
     hdl_render,
     hdl_gen,
-    aggregate
+    aggregate,
+    custom_doc
 ]
 
 for cmd in commands:

adi_doctools/cli/aggregate.py

@@ -201,98 +201,6 @@ def gen_symbolic_doc(repo_dir):
     pr.wait(p)
 
 
-def gen_monolithic_doc(repo_dir):
-    def add_pyadi_iio_to_path():
-        """
-        To allow importing adi.<module> for autodoc.
-        """
-        name = os.path.join(repo_dir, 'pyadi-iio')
-        if 'PYTHONPATH' in os.environ:
-            os.environ['PYTHONPATH'] += os.pathsep + name
-        else:
-            os.environ['PYTHONPATH'] = name
-    add_pyadi_iio_to_path()
-
-    d_ = os.path.abspath(os.path.join(repo_dir, os.pardir))
-    docs_dir = os.path.join(d_, 'docs')
-    indexfile = os.path.join(docs_dir, 'index.rst')
-    if os.path.isdir(docs_dir):
-        pr.run(f"rm -r {docs_dir}")
-    pr.mkdir(docs_dir)
-
-    mk = {}
-    for r in repos:
-        cwd = os.path.join(repo_dir, f"{r}/{repos[r]['doc_folder']}")
-        mk[r] = get_sphinx_dirs(cwd)
-        if mk[r][0]:
-            continue
-        pr.mkdir(os.path.join(docs_dir, r))
-        cp_cmd = f"""\
-        for dir in */; do
-            dir="${{dir%/}}"
-            if [ "$dir" != "_build" ] && [ "$dir" != "extensions" ]; then
-                cp -r $dir {d_}/docs/{r}
-            fi
-        done
-        for file in *.rst; do
-            cp $file {d_}/docs/{r}
-        done\
-        """
-        cwd = mk[r][2]
-        pr.run(cp_cmd, cwd)
-
-        # Prefixes references with repo name, except already external
-        # references :ref:`repo:str`
-        cwd = f"{d_}/docs/{r}"
-        patch_cmd = """\
-        # Patch :ref:`str` into :ref:`{r} str`
-        find . -type f -exec sed -i -E \
-            "s/(:ref:\\`)([^<>:]+)(\\`)/\\1{r} \\2\\3/g" {{}} \\;
-        # Patch:ref:`Title <str>` into :ref:`Title <{r} str>`
-        find . -type f -exec sed -i -E \
-            "s/(:ref:\\`)([^<]+)( <)([^:>]+)(>)/\\1\\2\\3{r} \\4\\5/g" {{}} \\;
-        # Patch ^.. _str:$ into .. _{r} str:
-        find . -type f -exec sed -i -E \
-            "s/^(.. _)([^:]+)(:)\\$/\\1{r} \\2\\3/g" {{}} \\;\
-        """.format(r=r)
-        pr.run(patch_cmd, cwd)
-
-        # Patch includes outside the docs source,
-        # e.g. no-OS include README.rst
-        depth = '../' * (2 + repos[r]['doc_folder'].count('/'))
-        include_cmd = """
-        find . -type f -exec sed -i -E \
-        "s|^(.. include:: )({depth})(.*)|\\1../../../repos/{r}/\\3|g" {{}} \\;\
-        """.format(r=r, depth=depth)
-        pr.run(include_cmd, cwd)
-
-    # Convert documentation into top-level
-    cwd = f"{docs_dir}/documentation"
-    pr.run(f"mv {cwd}/* {docs_dir} ; rmdir {cwd}")
-    pr.run(f"cp -r {mk['documentation'][2]}/conf.py {docs_dir}")
-    pr.run(f"echo monolithic = True >> {docs_dir}/conf.py")
-
-    for r in repos:
-        if r != 'documentation':
-            patch_index(r, docs_dir, indexfile)
-
-    # Convert external references into local prefixed
-    cwd = docs_dir
-    for r in repos:
-        ref_cmd = """\
-        find . -type f -exec sed -i "s|ref:\\`{r}:|ref:\\`{r} |g" {{}} \\;\
-        """.format(r=r)
-        pr.run(ref_cmd, cwd)
-    ref_cmd = """\
-    find . -type f -exec sed -i "s|<|<|g" {} \\;
-    """
-    pr.run(ref_cmd, cwd)
-
-    pr.run("sphinx-build . _build", docs_dir)
-
-    cwd = d_
-
-
 @click.command()
 @click.option(
     '--directory',
@@ -303,13 +211,6 @@ def add_pyadi_iio_to_path():
     required=True,
     help="Path to create aggregated output."
 )
-@click.option(
-    '--monolithic',
-    '-m',
-    is_flag=True,
-    default=False,
-    help="Generate a single Sphinx build."
-)
 @click.option(
     '--extra',
     '-t',
@@ -341,21 +242,17 @@ def add_pyadi_iio_to_path():
     default=False,
     help="Open after generation (xdg-open)."
 )
-def aggregate(directory, monolithic, extra, no_parallel_, dry_run_, open_):
+def aggregate(directory, extra, no_parallel_, dry_run_, open_):
     """
-    Creates an aggregated documentation out of every repo documentation,
-    by deafult, generate independent Sphinx builds for each repo.
-    To resolve inter-repo-references in symbolic mode, run twice.
+    Creates a symbolic-aggregated documentation out of every repo
+    documentation.
+    To resolve interrepo-references, run the tool twice.
     """
     global dry_run, no_parallel
     no_parallel = no_parallel_
     dry_run = dry_run_
     directory = os.path.abspath(directory)
 
-    if monolithic:
-        click.echo("Currently, monolithic output is disabled")
-        return
-
     if not extra:
         click.echo("Extra features disabled, use --extra to enable.")
 
@@ -370,7 +267,7 @@ def aggregate(directory, monolithic, extra, no_parallel_, dry_run_, open_):
     for r in repos:
         cwd = os.path.join(repos_dir, r)
         if not os.path.isdir(cwd):
-            git_cmd = ["git", "clone", lut['remote'].format(r), "--depth=1", "-b",
+            git_cmd = ["git", "clone", lut['remote_ssh'].format(r), "--depth=1", "-b",
                        repos[r]['branch'], '--', cwd]
             pr.popen(git_cmd, p)
         else:
@@ -381,14 +278,9 @@ def aggregate(directory, monolithic, extra, no_parallel_, dry_run_, open_):
     if extra:
         do_extra_steps(repos_dir)
 
-    if monolithic:
-        gen_monolithic_doc(repos_dir)
-    else:
-        gen_symbolic_doc(repos_dir)
+    gen_symbolic_doc(repos_dir)
 
-    type_ = "monolithic" if monolithic else "symbolic"
-    out_ = "docs/_build" if monolithic else "html"
-    click.echo(f"Done, {type_} documentation written to {directory}/{out_}")
+    click.echo(f"Done, documentation written to {directory}/html")
 
     if open_ and not dry_run:
-        subprocess.call(f"xdg-open {directory}/{out_}/index.html", shell=True)
+        subprocess.call(f"xdg-open {directory}/html/index.html", shell=True)