Doctools - Visual Studio Code Extension

[!IMPORTANT] Doctools is not an official product of Analog Devices Inc. It is a collection of open-source tools bundled as an extension and is provided without support or warranty.

Overview

A Visual Studio Code extension that provides language support for reStructuredText (RST) documentation, powered by tree-sitter. This extension offers intelligent editing capabilities for Sphinx documentation projects, with support for custom roles and directives by interfacing with the Sphinx Python object directly.

Key Features

• Tree-sitter Syntax Highlighting: Fast, accurate syntax highlighting for reStructuredText files using tree-sitter parsing
• Smart Hover Information: Display detailed information about roles and directives on mouse or keyboard cursor hover
• Intelligent Auto-completion:
  • Roles (:ref:, :doc:, ...)
  • Directives (.. note::, .. figure::, ...)
  • Local and external references (:doc:, :external+inv:ref:, ...)
• Live Server: Automatically build changes on save, and see the changes highlighted in the browser.
• Diagnostics: Display build warnings and errors as diagnostics in the editor
• Language Injection: Syntax highlighting for embedded languages blocks (bash, YAML)

Requirements

• Python 3 with virtual environments.
• Grammar correction (local, optional): OpenJDK (Java)

If you plan to use grammar correction only through the Language Tool API, Java is not required

Linux/Mac:

For local grammar correction, install OpenJDK from you package manager.

Windows

It is highly recommended to install under WSL2 and use the store your files in the WSL file system.

If for unknown reasons you still want to use on native Windows follow the lines below.

For grammar correction, install OpenJDK from the Microsoft distribution (direct link). Must re-open VSCode (not just reload the window).

sphinx, adi-doctools are installed automatically (with user confirmation) at ./.venv (current workspace/open folder). Do not open the sphinx source folder as the workspace folder, it may consider the venv files as source files.

Commands

Alternative

Esbonio is an extensively developed Language Server Protocol and Visual Studio Code extension for sphinx.

The Doctools cli is generates Estobio pyproject.toml entry with (including Sparse builds):

adoc serve --esbonio --sparse docs/learning | tee pyproject.toml

Third Party Sources

This extension proudly integrates the following open source projects:

Documentation

For comprehensive documentation on the Doctools project, visit:

analogdevicesinc.github.io/doctools