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

Ensure pip is newer than 23.0 [1]:

~$

pip install pip --upgrade

Install the documentation tools, which will fetch this repository release:

~$

pip install adi-doctools

Test it building this documentation:

~$

(cd docs ; make html)

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

Neovim support

A Neovim extension is available to add support and actions to the documentation. By using the modern [tree-sitter](https://tree-sitter.github.io/), the parser is extended to understand the custom directives and roles, including adding actions to preview and open links.

To install, add to your LazyVim configuration:

{
  'analogdevicesinc/doctools',
  branch = 'nvim'
  config = function()
    require("adi-doctools").setup()
    vim.keymap.set('n', '<leader>rr', '<cmd>DInspect<cr>')
    vim.keymap.set('n', '<leader>ra', '<cmd>DACtion<cr>')
  end,
}

Configure the shortcut as desired.

Make sure you have common parsers installed, at least:

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

You can inspect the tree with :InspectTree.

Not-implemented:

  • .md support.

LaTeX support

Beyond the HTML harmonic theme, limited LaTeX support is available. To build you will need, at least:

~$

zypper install \
   texlive-latexmk \
   texlive-collection-basic \
   texlive-collection-latex \
   texlive-collection-latexrecommended \
   texlive-collection-latexextra \
   texlive-collection-fontsrecommended \
   texlive-fncychap \
   gnu-free-fonts texlive-gnu-freefont texlive-gnu-freefont-fonts

Due to unicode support, latex_engine is set to xelatex internally if the value is Sphinx default’s pdflatex. If latex_elements['fontpkg'] is not provided, a default is also set with unicode characters.

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