Installing

How to do a release install, and a development install of Doctools.

Guaranteed to work with Python 3.8 or newer and distributions released on or after 20H1 (e.g., Ubuntu 20.04 LTS).

Release install

~$

python3 -m venv venv

~$

source venv/bin/activate

# Ensure pip is newer than 23.0 (https://github.com/pypa/setuptools/issues/3269)

~$

pip install pip --upgrade

~$

pip install adi-doctools

~$

pipx install adi-doctools

~$

uvx --from adi-doctools adoc

Test it building this documentation:

~$

(cd docs ; make html)

MCP integration

The tool includes a slim MCP to expose the CLIs. It simply teaches the LLM of the tools available, analogous as a skill file. This methodology ensures the context window is not penalized.

To configure the MCP to your AI coding harness, first install with the MCP add-in:

~$

python3 -m venv venv

~$

source venv/bin/activate

~$

pip install 'adi-doctools[mcp]'

~$

pipx install 'adi-doctools[mcp]'

~$

uvx --from 'adi-doctools[mcp]' adoc-mcp

With the tool installed, add to your favorite AI code harness:

~$

opencode mcp add adoc -- $(which adoc-mcp)

~$

claude mcp add adoc -- $(which adoc-mcp)

~$

codex mcp add adoc -- $(which adoc-mcp)

~$

gemini mcp add adoc -- $(which adoc-mcp)

Tip

The which adoc-mcp is to invoke the tool by the absolute path, without having to explicitly activate the python virtual environment (most useful for the pip install method).

For coding harness without MCP support, such as pi coding harness, you can create a skill based on the tools descriptions at adi_doctools/mcp/server.py.

Using a Python virtual environment

Installing packages at user level through pip is not always recommended, instead, consider using a Python virtual environment (python3-venv on ubuntu 22.04).

To create and activate the environment, do before the previous instructions:

~$

python3 -m venv .venv

~$

source .venv/bin/activate

Don’t create the .venv inside the docs/ folder, since its files will be caught by the Sphinx builder.

Use deactivate to exit the virtual environment.

For next builds, just activate the virtual environment:

~$

source .venv/bin/activate

GitHub release archive

Beyond PyPi, the package is also stored as GitHub releases:

VScode/VScodium support

There are two options for Visual Studio Code support:

Doctools provides support to LanguageTool for grammar correction and GUI support for Sparse builds.

Esbonio tips

Setup the virtual environment first before opening the text editor, to avoid triggering fallback behaviours.

Serve is able to generate Estobio pyproject.toml entry with (including Sparse builds):

~/git-repo$

adoc serve --esbonio \
    --sparse docs/docs_guidelines docs/cli.rst | tee -a pyproject.toml

Neovim support

Esbonio is an extensively developed Language Server Protocol for sphinx. See How To Integrate Esbonio with Neovim.

It is also recomemded to use the modern tree-sitter. Make sure you have common parsers installed, at least:

:TSInstall rst
:TSInstall markdown
:TSInstall yaml
:TSInstall json

You can inspect the tree with :InspectTree.

PDF LaTeX support

Beyond the HTML harmonic theme, limited LaTeX support is available. The LaTeX build is divided in two steps, the LaTeX files generation, and then the PDF generation. For the LaTeX files generation, install cairosvg with pip|pipx|uvx.

For the PDF generation, execute the same steps as provided in the ci/Containerfile.latex. Without the tlmgr util, most distros ship the same packages suffixed with texlive-, e.g., wrapfig -> texlive-wrapfig.

With the container (~1.6 GB), the end-to-end usage is:

# pip or pipx or uvx

~$

pip install adi-doctools[pdf]

# podman or docker

~$

podman build -t adi/doctools_latex:latest \
   -f https://raw.githubusercontent.com/analogdevicesinc/doctools/main/ci/Containerfile.latex

~$

cd docs

# Build latex to _build/latex

~/docs$

sphinx-build -M latex "." "_build" -j auto

# Build pdf inside the container

~/docs$

podman run --rm  -v $(pwd)/_build/latex:/work -w /work adi/doctools_latex:latest make

Due to unicode support, latex_engine is set to xelatex internally if the value is Sphinx default’s pdflatex.

If you are adding support to LaTeX for a directive or role, see 224f5755415c for an example on how to add ‘visitors’ for latex builder.

Development install

Development install allows editing the source code and applying changes without reinstalling. Also extends Serve to watch changes on the webpage source code (use –dev/-r option to enable this).

Install the web compiler

If you care about the web scripts (js modules) and style sheets (sass), install node.js, npm and the npm packages below, if not, read this section’s last paragraph.

Note

If the npm provided by your package manager is too old and updating with npm install npm -g fails, consider installing with NodeSource.

At the repository root, install the npm dependencies locally:

~$

npm install rollup \
     @rollup/plugin-terser \
     sass \
     --save-dev

  • rollup/plugin: Module bundler.

  • @rollup/plugin-terser: Minified bundle with terser.

  • sass: CSS stylesheets.

If you choose to not use npm, you can obtain pre-built web-scripts from the latest release. For that, just run Serve after the repository is installed and confirm the prompt that will appear.

Fetch third-party resources

Fetch third-party fonts:

~$

./ci/fetch-fonts.sh

Install the repository

Finally, do a symbolic installation of this repo:

~$

pip install -e . --upgrade

Caution

If using a python virtual environment for the requirements.txt packages, do this command with the virtual environment already activated.

Mixing pip packages inside and outside the virtual environment will cause packages outside the environment to not have access to the packages inside of it, breaking most CLIs.

Neovim support

Add to you lazyvim config the path to the branch nvim:

{
  dir = '/path/to/doctools/nvim',
  -- ...
}

Removing

To remove, either release or development, do:

~$

pip uninstall adi-doctools