Sphinx projects and domain references

Establish the documentation root#

Open the Sphinx documentation with conf.py and its source tree available. Configure the plugin’s project/Sphinx settings when the docs are nested inside a larger repository. The documented release detects supported Sphinx executable paths, but your chosen environment must contain the project’s extensions.

A minimal root document can contain:

Example manual
==============

.. toctree::
   :maxdepth: 2

   setup
   api

Create the referenced documents and use completion/navigation on their paths. A toctree entry normally omits the .rst suffix.

Resolve labels and documents#

In setup.rst, define a label before its section:

.. _first-run:

First run
---------

Start the service and check its status.

Reference it with :ref:`first-run`. Use :doc:`setup` for a document reference. Invoke completion inside the role and Go to Declaration on its target.

Resolve domain objects#

A Python-domain declaration and reference might be:

.. py:function:: example.calculate_total(prices)

   Return a total in cents.

See :py:func:`example.calculate_total`.

Domain-qualified names avoid confusing an object with a similarly named plain label. Project intelligence uses the available declarations/context; objects generated only by an external extension can require the actual Sphinx build to resolve fully.

Diagnose unresolved targets#

Check spelling, explicit labels, domain/module context, root selection, and whether the target content is available locally. A duplicate-label warning and a missing-target warning require different fixes. Do not silence both by adding a second copy of a label.

Build the project’s documentation after changing navigation or public references so Sphinx can validate extension-dependent relationships.