PDM Docs: Generating a Sphinx-style Python object inventory (to allow reST cross-references from Sphinx-based documentation)

[sr-murthy]

Is your feature/enhancement proposal related to a problem? Please describe.

Currently, it is not possible to make markup cross references from Sphinx-based documentation projects, which are written in reStructuredText (reST), to MkDocs-based documentation projects such as the PDM docs.

In particular, it is not possible currently to write markup links to PDM Python objects (such as functions, classes, methods etc.) documented in the PDM API or the CLI API from Sphinx-based projects using Sphinx directives and roles in the Sphinx Python domain.

This is because for Sphinx projects to link to the PDM documentation, the PDM documentation must be built with a Sphinx-style "object inventory", which is "a mapping from object names to URIs relative to the HTML set’s root", as described in the Sphinx intersphinx extension documentation. This is the Sphinx tool that makes it possible to write markup links between any two Sphinx projects (as long as both are configured with the intersphinx extension).

Of course, MkDocs is independent of Sphinx, but there is a simple configuration-based solution to this problem which is described in the next section.

To provide some context and an illustration of what this might look like, we can consider how markup links to notable Python documentation projects, such as Python standard library / API (and many other prominent Python documentation projects, such as Pandas, Numpy, matplotlib) currently work.

For example, the following reST markup is valid in any Sphinx project:

:py:class:`pathlib.Path`
:py:meth:`json.JSONEncoder.encode`
:py:func:`re.match`

and a HTML build will generate HTML hyperlinks to the correct documentation targets pathlib.Path, json.JSONEncode.encode, and re.match, respectively, which are included as objects in the Sphinx object inventory generated for the Python standard library / API:

$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv | grep -E 're.match$|pathlib.Path$|json.JSONEncoder.encode$'
    pathlib.Path                                                                     : library/pathlib.html#pathlib.Path
    re.match                                                                         : library/re.html#re.match
    json.JSONEncoder.encode                                                          : library/json.html#json.JSONEncoder.encode

It should be noted that for these references to work in the source Sphinx projects the intersphinx mapping for the target Sphinx project must be defined in the source project conf.py, e.g. for Python:

# Intersphinx mappings to reference external documentation domains
intersphinx_mapping = {
    ...
    'python': ('https://docs.python.org/3', None),
    ...
}

The same should be possible with PDM as long as the PDM HTML documentation is built with a Sphinx-style object inventory. So, for example, it should be possible to make markup references from Sphinx projects to PDM functions, classes, methods (or any other public API objects), e.g.:

:py:func:`pdm.resolver.core.resolve`
:py:class:`pdm.models.backends.PDMBackend`
:py:meth:`pdm.core.Core.create_project`

assuming that these PDM targets have docstrings and the Sphinx projects have defined the intersphinx mapping for the PDM documentation:

# Intersphinx mappings to reference external documentation domains
intersphinx_mapping = {
    ...
    'pdm': ('https://pdm.fming.dev/latest/', None),
    ...
}

The solution is described in the next section.

Describe the solution you'd like

The solution is to make a single change to the PDM MkDocs YML in the plugins.mkdocstrings section:

plugins:
- mkdocstrings:
    ...
    enable_inventory: true
    ...

As implied by the MkDocs documentation setting enable_inventory to true would result in the PDM HTML documentation generating a Sphinx-style object inventory, which would support cross references from Sphinx projects.

The Sphinx projects wanting to link to PDM documentation would have to define the intersphinx mapping appropriately, and it should be something like this:

# Intersphinx mappings to reference external documentation domains
intersphinx_mapping = {
    ...
    'pdm': ('https://pdm.fming.dev/latest/', None),
    ...
}

[sr-murthy]

@frostming I'd like to submit the change as a PR.

[sr-murthy]

P. S. Checking the object inventory file (objects.inv) exists:

python -m sphinx.ext.intersphinx 'https://pdm.fming.dev/latest/objects.inv'