Advanced configuration
Configuration, extension development, and theme internals. For writing pages, see Documentation guidelines; for building and publishing, see Command line interface and Versioned.
Third-party extensions
Repositories have the freedom to choose the third-party extensions they want to include in their documentation. They are listed in the requirements.txt file, and are installed with:
pip install -r requirements.txt
Register the extensions in conf.py.
The recommendation is to avoid using extensions that render content on the client-side using JavaScript, because this requires:
Fetching third-party scripts from someone else’s server most of the time.
Patching or replacing the renderer to export to other formats, such as PDF.
Managing these added scripts to ensure they apply on hot reload.
Support custom JavaScript in hot reload
Hot reload replaces page content without reloading the browser document.
Scripts that only initialize on DOMContentLoaded will not automatically
process the replacement content.
See adi_doctools/theme/harmonic/scripts/hot_reload.js:
sync_scripts tracks page scripts and ensure_script handles loading
and reinitialization. Existing MathJax and Mermaid integrations illustrate
how to rerender content when their scripts have already loaded.
For example, for MathJax, that is simply calling the global method
MathJax.typeset() to process the new page if it includes the script.
For a new integration:
Initialize both on the first page and after content is replaced.
Release listeners, observers, and generated DOM before leaving the page.
Make repeated initialization safe: do not duplicate controls or listeners.
Test links and browser back/forward within a page, between builds, and between repositories, including pages without the extension.
Provide a build-time alternative for content needed in PDF or text output.
Theme modules can use the app:hot_reload:page_unload and
app:hot_reload:page_loaded events.
Repository-specific extensions
Add repository-specific directives and roles under ext/, and load them
from conf.py:
import os
import sys
sys.path.insert(0, os.path.abspath('ext'))
extensions = [
'adi_doctools',
'ext_repo_name',
]
Create the ext/ext_repo_name.py and implement your custom directives/roles. Replace repo_name with your repository name.
Tip
If you think your extension could be useful for other repositories, consider migrating it to Doctools source code.
Supporting custom documents
If the extension relies on files at the repository (like XML files), and/or
uses either env.found_docs or docnames to manage cache, check if
env.config.monolithic exists and is true.
If yes, prefix:
File paths with the relative path from the custom doc to the repository (always
../<repository>, e.g.../hdl).Docnames with the repository name (e.g.
hdl/).
This ensures compatibility with Custom Doc.
Custom doc copies the original source directory to
env.srcdir/<repository> to avoid page conflicts when aggregating.
For example, if the normal documentation source is
repo_name/doc/sphinx/source and the artifact is
repo_name/builds/info.xml:
from os import path
if getattr(env.config, 'monolithic', False):
repo_root = path.join(env.srcdir, '..', 'repo_name')
else:
repo_root = path.join(env.srcdir, '..', '..', '..')
artifact_path = path.abspath(path.join(repo_root, 'builds', 'info.xml'))
The relative path to the repository root depends on its documentation source directory. In a combined build, the first document-name component identifies the repository. Prefix cached document names with it:
prefix = 'repo_name' if getattr(env.config, 'monolithic', False) else '.'
docname = path.join(prefix, 'tutorial', 'index')
For intermediary files, for example a SQLite database, it is recommended
to anchor to outdir/../managed:
managed_dir = path.abspath(
path.join(env.app.builder.outdir, '..', 'managed'))
sql_path = path.join(managed_dir, 'my_repo.sqlite')
Documentation version configuration
To avoid having the version set in multiple places or having to tweak
conf.py to obtain it from somewhere else, continuous integration can set
the environment variable ADOC_DOC_VERSION to set the version value.
The version value on conf.py has lower precedence, and will be
overwritten if ADOC_DOC_VERSION is set.
The CI, in general, should set ADOC_DOC_VERSION as the current checkout
branch or tag (e.g. main, v1.0.0). For GitHub Actions, that can be
${{ github.ref_name }}:
env:
ADOC_DOC_VERSION: ${{ github.ref_name }}
Quick cheat sheet for github.ref_name values on event:
push branch:
main,dev, …push tag:
v2.2.2,new-feature, …pull_request:
1234/merge,23/merge, …
If both the environment variable and version on conf.py are unset,
it defaults to an empty string.
This documentation-build version is separate from feature history recorded
using version directives. For deployment layouts
and the tags.json formats, see Versioned.
Advanced cross-repository references
Start with External references sphinx. Doctools’ interref_uri configuration or
ADOC_INTERREF_URI environment variable changes the base documentation URL
(default: https://analogdevicesinc.github.io/).
With interref_local = True, Doctools also looks for documentation sources
in neighboring repository checkouts. Their paths are resolved using
adi_doctools/lut.py.
Private repositories
Configure private inventories separately:
interref_private_repos = ['krabby-patty-recipe', 'x-files/v1.1']
Authentication uses GITHUB_TOKEN or git credential fill. Do not put
credentials into documentation sources.
Inspecting an inventory
To list the targets available in an external inventory:
python -m sphinx.ext.intersphinx \
https://analogdevicesinc.github.io/hdl/objects.inv
Use the explicit :external+inventory:ref: form for compatibility with
Sphinx 7. Sphinx 8 also supports inventory-qualified :ref: targets;
adoc adapts references when assembling custom documents.
Numbering configuration
Enable figure, table, and code-listing references with numfig = True in
conf.py. Customize their prefixes with numfig_format:
numfig = True
numfig_format = {
'figure': 'Figure %s',
'table': 'Table %s',
'code-block': 'Listing %s',
'section': 'Section %s',
}
Tip
By default enumeration is global. If the
toctree is not numbered to divide the pages
into numbered sections (e.g. Figure 3.4.4), numbering continues across
pages.
To have the numbering reset at every page, add numfig_per_doc = True
to conf.py.
Git Large File Storage
Where applicable, Git Large File Storage (LFS) is used to replace large files with text pointers inside Git, reducing cloning time.
To setup, install from your package manager and init:
apt install git-lfs
git lfs install --skip-smudge
The files that will use Git LFS are tracked at .gitattributes, to add new
files use a pattern at the repo root, for example:
git lfs track '*.jpg'
Or edit .gitattributes directly.
For publishing LFS-backed assets, see Documentation deployment.
Importing from DokuWiki
The old wiki uses DokuWiki. Use the following command to import a DokuWiki page (old wiki.analog.com):
pandoc imported.txt -f dokuwiki -t rst --columns=80 \
--list-tables -s -o imported.rst
The --list-tables parameter requires pandoc-types >= 1.23, included
in any recent Pandoc release;
if it is not an option, remove it and export in the grid table format
(see Tables sphinx for more information).
After converting, update it to conform with Documentation guidelines, and make sure to use our directives and roles, for example, the Git.
To speed things up, combine with wget:
wikifile=resources/eval/user-guides/adrv9009/adrv9009
wget -O - "https://wiki.analog.com/$wikifile?do=export_raw" --no-verbose | \
pandoc -f dokuwiki -t rst --columns=80 --list-tables -s -o output.rst
Also, consider recording macros in your favorite text editor to automate repetitive steps.
There is also the DokuWiki to Sphinx (bash.sh) to further help importing.
Dynamic theme elements
Dynamic elements refer to sections of the documentation that are updated using dynamically loaded metadata, scripts, and styles (modules).
The dynamic elements implemented:
doctools/metadata.json:The navigation bar at the top (
repotocentry).A banner at the top (
bannerentry).
The metadata/modules files are generated when core_repo is true in
conf.py. The metadata also contains the list of extra scripts and styles.
The JavaScript fetches metadata.json from the Doctools deployment.
For documentation hosted under a shared path, this is
{origin}{subhost}doctools/metadata.json. Standalone and offline builds
use https://analogdevicesinc.github.io/doctools/metadata.json.
See adi_doctools/theme/harmonic/scripts/fetch.js for URL
resolution.
To add new JavaScript modules and CSS styles:
Update ci/rollup.config.app.mjs.
Add the list of modules to adi_doctools/lut.py.
The generated modules are published in _static, alongside the base
app.umd.js and app.min.css. Loading modules from the Doctools deployment
allows them to be updated across documentation releases without rebuilding
each release.
Example use cases/suggestions:
A search module that follows the natural evolution of the documentation.
A unified footer across releases, using DOM manipulation by a
footer.umd.jsmodule.
For theme development, use Serve with -r to watch JavaScript,
styles, and documentation together. Different ports are different origins;
check the ports if cross-origin requests fail.