feature: Manually specify external docs url for docs without objects.inv

ItsDrike commented 1 month ago

Is your feature request related to a problem? Please describe.

Some projects use custom documentation that doesn't generate the objects.inv file. For these projects, cross-linking to their docs is currently not really possible.

Describe the solution you'd like

It would be nice if it was possible to specify some concrete object -> url mappings right from the config e.g.:

plugins:
  - mkdocstrings:
      handlers:
        python:
          import:
            - url: https://docs.python.org/3.13/objects.inv
              domains: [std, py]
            - https://typing-extensions.readthedocs.io/en/latest/objects.inv
            # Proposed new section:
            - objects:
                - httpx.AsyncClient: https://www.python-httpx.org/api/#asyncclient
                - httpx.Client: https://www.python-httpx.org/api/#client

Describe alternatives you've considered

It would probably be possible to write the objects.inv file for the docs of the external project manually and then host is somewhere for mkdocs to pull it. However, the objects.inv format isn't that common and I'm not sure how easy would generating it like this be. The content of this file seems to be compressed, which makes writing it by hand impossible.

Boost priority

Boost priority in our backlog through Polar.sh. Higher pledge, higher priority.
Minimum pledge by user/organization is $5, minimum amount for boost is $30.
View all issues with pledges.
We receive the funds once the issue is completed and confirmed by you.
Features with the insiders label are released to sponsors first, and tied to a funding goal.

pawamoy commented 1 month ago

Hi @ItsDrike, thanks for the feature request. That sounds like a good feature indeed. I'm not convinced by the list directly within mkdocs.yml, so maybe we'll rather accept relative file paths to JSON inventory files. That means we'll have to design these JSON files first (but that shouldn't be hard, it's basically objects.inv uncompressed, formatted in JSON, with optional fields).

In tandem, I'd highly recommend that you reach out to HTTPX's maintainers to see if they would be interested in using mkdocstrings for their API docs, so that their users can cross-reference it through the autogenerated objects.inv file :slightly_smiling_face:

pawamoy commented 1 month ago

I wonder if there wouldn't be a way for us to automate that further. I'm imagining deploying API docs for HTTPX, with a single page containing all headings (that's just the requirement for generating the objects.inv file with everything in it), but actually put some Javascript in this page that reuses the anchor in the URL to redirect to the actual API docs of HTTPX. We'd maintain these mappings in a centralized repository instead of asking each user to maintain their own copy.

ItsDrike commented 1 month ago

Hi @ItsDrike, thanks for the feature request. That sounds like a good feature indeed. I'm not convinced by the list directly within mkdocs.yml, so maybe we'll rather accept relative file paths to JSON inventory files. That means we'll have to design these JSON files first (but that shouldn't be hard, it's basically objects.inv uncompressed, formatted in JSON, with optional fields).

Yeah, that would be fine too, I wonder if it's not overdoing it though, since I doubt there's that many docs without objects.inv, it's probably a pretty rare case and having another file just for this in a project could be annoying, but I personally wouldn't mind it either way.

In tandem, I'd highly recommend that you reach out to HTTPX's maintainers to see if they would be interested in using mkdocstrings for their API docs, so that their users can cross-reference it through the autogenerated objects.inv file 🙂

Already did that haha (here) and they did agree to switch eventually, but nevertheless, this would be a really nice feature.

I wonder if there wouldn't be a way for us to automate that further. I'm imagining deploying API docs for HTTPX, with a single page containing all headings (that's just the requirement for generating the objects.inv file with everything in it), but actually put some Javascript in this page that reuses the anchor in the URL to redirect to the actual API docs of HTTPX. We'd maintain these mappings in a centralized repository instead of asking each user to maintain their ow

Definitely an interesting idea, I'd still love to see an option to manually specify the objects locally, I think it could be useful for things that haven't yet made it into that central repo, or maybe for closed source/internal stuff.

mkdocstrings / python