sphinx
sphinx copied to clipboard
Add a new ``references`` builder
This PR add a new builder references
, to build a single references.json
, which provides a mapping for almost* all targets available to reference in the project, including:
- Internal domain objects, generated within the current project
- External domain objects, loaded from the
objects.inv
configured viaintersphinx_mapping
(when using thesphinx.ext.intersphinx
extension)
* I say almost, because this assumes the objects returned from domain.get_objects
account for the majority of referencable items in a project, but there are currently some notable exceptions, like the math
domain not returning any (but that is for another PR to fix)
This partialy addresses #12152, to allow for a clear way for users to understand:
- What targets are available for them to reference
- How to reference these targets
Crucially, the references.json
includes the mapping of object type
to role names
(this can be one-to-many),
since a role name is required for the reference syntax, not the object type.
I would also invisage other tools (like VS Code extension) could utilise this, to provide things like auto-completions, and "jump to target/references"
Some considerations:
-
I feel a builder is really the only way to do this comprehensively; having a standalone CLI (like the current
python -m sphinx.ext.intersphinx
) can only get you so far, and then you will have to start re-implementing features of a normal sphinx build (like reading configuration, etc) -
Perhaps in a follow up PR I could introduce a complimentary CLI, that reads the
references.json
and allows users to quickly generate references. Something likesphinx-ref find 're.Match'
returning:class:`~re.Match`
(i.e https://github.com/orgs/sphinx-doc/discussions/12152#discussioncomment-8862652) -
There are cases where an
object type
has no matchingrole names
, this PR is not addressing that (although I want to eventually) -
As I mention in #12152, it would be ideal for this to include, not just the document path where a local target is defined, but also the line number (if available). But this is not within the scope of this PR
-
Creating a singular
references.json
is probably the simplest way to do this. But, it could get rather large, for a large project, or one with lots of intersphinx mappings. Is this ok, or do we think another format would be better, like one JSON file per domain / object type, or even something like an sqlite database file? -
The other non included in this PR, is any additions to the documention, I could do this here or in a follow-up PR