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

gastmaier commented 5 days ago

Uses human friendly YAML files, e.g.:

# Custom doc builder template
# ---------------------------

# Add dirs and files to include per repo
doc:
  hdl:
    - user_guide
    - projects/ad3552r_evb
    - projects/ad4110
    - library/spi_engine

  no-OS:
    - contributing.rst
    - projects/eval-adis1657x.rst

  documentation:
    - linux/kuiper

# Per repo configuration
# extra: do steps that require extra software (e.g. vendor sdk)
# branch: clone from a specific branch, overwrites "main"
config:
    hdl:
      branch: "my-branch"
    no-OS:
      extra: true

# Include extra extensions
extensions:
    - sphinx.ext.duration

project: "Custom user guide"

Missing features:

Empty sections remover

After filtering the toctrees, some sections used to add captions to toctrees (e.g. ADCs, Obsolte IPs, etc) are left empty. those could be removed.

Missing caution:

Figure out exactly if the tool works with all Sphinx version supported. (Fixed v1) In particular, it relies on parsing error with the suffix [some.thing] e.g. [ref.ref] and I remember not seeing it on every sphinx output. Is this configurable or something added later/before? (Fixed v1)

Not passing media_print (Fixed v1)

Check if grabbed extensions are installed on the system before calling sphinx, to gracefully fail (Fixed v1)

If a subprocess fail (eg. git clone with no internet/ssh key) gracefully return instead of keep going (Fixed v1)

gastmaier commented 2 days ago

V0 -> V1

Custom-doc

Rename doc-build to custom-doc
Check for return code in git clone, hinting --https
Add show_warning_types = True to custom-doc/conf.py (is True by default only for sphinx v8.0.0)
Check for missing extensions
Patch internal references for sphinx < v8.1.0 (sphinx commit 0bfaadf6c9)
Pass media_print on builder pdf
Minor doc improvement.

Author-mode

Use python sphinx class.
Pass media_print on builder pdf

General

Check only if media_print env variable exist, regardless of the value (to match dev_pool var behaviour)

gastmaier commented 1 day ago

V1->V2

Patch&render LaTeX math with matplotlib.mathtext (see #21)
Extend media_print info, revert some of the changes in favor of WeasyPrint

Remaining caution:

Table of contents depth: some depths are too shallow, hiding sub levels that could be shown. Perhaps patch this option during the custom doc code gen? Or tune directly on the docs source codes?

Missing nice to have:

Collapsible could have a no-print flag option to hide for pdf output (e.g. full logs)). And maybe try to add a id-anchor-permalink to replace with (similar to the video placeholder)?

analogdevicesinc / doctools