Need a way to organize multiple documentation "projects"

[cgay]

We need a good way to provide links between the Library Reference, Hacker Guide, Getting Started, and others, each of which is a separate Sphinx "project".

InterSphinx might be a good way to do this.

Long term, I picture the Library Reference being broken apart into individual projects for each library, and documenting those alongside documentation from all projects in the pacman catalog.

[cgay]

I posted https://groups.google.com/g/sphinx-users/c/CcnnXV2LOoY but got no response.

[cgay]

The answer to my question turned out to be pretty darned simple but the intersphinx docs don't make it very clear. If we have

intersphinx_mappings = {
    'http': ('https://opendylan.org/documentation/http/', None)
}

Then a link to the add-resource function in the HTTP docs looks like this

:func:`http:add-resource`

And there was much rejoicing.

[cgay]

See the above commit for a start, but there are some issues remaining to work out, as mentioned in that PR. Also on sphinx-users they said (if I understood correctly) that both of these should work, barring multiple definitions with the same name in different libraries:

:func:`library-reference:foo`
:func:`foo`

So that needs testing.

[cgay]

Also also, we need to be able to test the intersphinx_mapping locally before publishing doc changes. There's a mechanism for this but I decided to leave it for a later time.

[cgay]

This has all been fixed by the recent website revamp. Everything is built as a unit and references are just Sphinx :doc:... references.