Rustdoc: interest in producing intersphinx index files?

documentation
1

intersphinx works through an index file (usually "objects.inv") which seems to have a relatively simple structure.

I figure it could be useful for rustdoc to produce such an index (alongside any index it already does provide) for:

  • interop with sphinx itself (so it's possible to flexibly link from sphinx documentations to rustdoc objects)
  • because some folks have built tooling which leverages that e.g. doc2dash which apparently uses the index / inventory file to generate docsets (there may be other)

Eventually it might also be nice for rustdoc to ingest such indexes in order to more easily cross-link to external documentations (whether for rust or not), this could allow rustdoc to support not just intra-doc links but inter-doc links (though the doc-level UX would have to be specified).

2

Is it possible to generate that format using the existing json output? I would prefer that to maintaining another format for rustdoc.

6 Likes
3

It probably can be generated from the (still-unstable) JSON output, but

Extending intra-doc links to support consuming Sphinx indexes would need a rustdoc extension. If someone wants to make an RFC for this, both features should be proposed at once (they can still be stabilized at different times).

1 Like
4

Consuming the sphinx format makes sense to me, because it can't be replicated outside rustdoc. I don't see why emitting the format has to be in rustdoc itself, though.

5

Three reasons:

  1. You would want everything on docs.rs to support it automatically. That still doesn’t mean it needs to be in rustdoc, but it does mean the team is taking responsibility for it working.

  2. Consuming these files is going to be the complicated part. Producing them doesn’t look any harder than redirects.json.

  3. Producing this file is going to include designing a Rust “domain”. None of this is going anywhere until a plan for that gets worked out.

1 Like
6

Where should that go, a PR on GitHub - rust-lang/rfcs: RFCs for changes to Rust?

7

Yes, there. Probably draft it first, and post it here, then when it seems mostly-good, post it to the rust-lang/rfcs repo.

I would also try to solicit feedback from (other?) sphinx subject-matter experts, like someone who's written a widely-used plugin or who's done this type of integration with other doc generators before.

1 Like
8

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.