sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

Add a new ``references`` builder

Open chrisjsewell opened this issue 11 months ago • 11 comments

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:

  1. Internal domain objects, generated within the current project
  2. External domain objects, loaded from the objects.inv configured via intersphinx_mapping (when using the sphinx.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:

  1. What targets are available for them to reference
  2. 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:

  1. 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)

  2. 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 like sphinx-ref find 're.Match' returning :class:`~re.Match` (i.e https://github.com/orgs/sphinx-doc/discussions/12152#discussioncomment-8862652)

  3. There are cases where an object type has no matching role names, this PR is not addressing that (although I want to eventually)

  4. 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

  5. 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?

  6. The other non included in this PR, is any additions to the documention, I could do this here or in a follow-up PR

chrisjsewell avatar Mar 23 '24 18:03 chrisjsewell