Enable intersphinx for documentation (aka expose `objects.inv` aka support)

[gabrielfalcao]

Hello thanks for this great project. I'm using pendulum extensively at work and would love to link to the pendulum documentation by using intersphinx

For that to work pendulum's documentation need to expose an objects.inv but I could not find it, here is a list of urls I tried:

• pendulum.eustace.io/docs/objects.inv
• pendulum.eustace.io/latest/objects.inv
• pendulum.eustace.io/objects.inv

Here are some examples of sphinx-based documentations and their respective objects.inv:

• https://botocore.readthedocs.io/en/latest/objects.inv
• http://click.pocoo.org/latest/objects.inv
• https://python-consul.readthedocs.io/en/latest/objects.inv
• http://flask.pocoo.org/docs/latest/objects.inv

Please expose that on pendulum so we can link to its documentation ?

[ashb]

Given that the docs aren't written in sphinx I am guessing this is non-trival

[cblegare]

@ashb It is indeed not trivial.

One could assemble an Inventory manually using sphobjinv but this would be tedious.

But Sphinx is one of the best documentation processor in my opinion, and its intersphinx is simply amazing.

More and more libraries use Mkdocs, no sphinx, no inventory (FastAPI, Pydantic, to name a few). Theses along with Pendulum developers take a great care to write good documentation and this is nice. I get that some people might prefer Markdown over RestructuredText, but still, not leveraging Sphinx and not offering integration for Sphinx users saddens me a bit, even more because of the fact that Sphinx is optimised for prose (unlike Doxygen, for instance) and not for generated API doc.

I would like to read about the advantages of Mkdocs and why it is chosen over Sphinx. Easier to style? Hate of RestructuredText (which is sometimes a bit akward I agree)?

If there could be a compromise possible, I'd try to submit PRs to Sphinx, user libraries, extensions or Mkdocs if anything could be done to help.

EDIT: If maintainers here would like to try, I would be glad to migrate the docs in Markdown to a Sphinx project as a proof of concept in a PR. I cannot implement the Pendulum custom style since I am so bad at CSS and JS, but I would be glad to do all the rest, including build scripts, documentation, training etc.

[Jorricks]

Let me break the silence here: It appears we are now using mkdocs to build the docs. We could simply add a mkdocs plugin called mkdocstrings which also supports this Sphinx inventory files. As example: The additions to the mkdocs.yml configuration could look like this:

# Plugins
plugins:
  - mkdocstrings:
      enable_inventory: true
      handlers:
        python:
          import:
          - https://docs.python.org/3/objects.inv
          options:
            show_root_heading: true
            docstring_style: sphinx
            show_signature_annotations: false
            show_source: true
            docstring_options:
              ignore_init_summary: yes

What we'd have to check for is whether mkdocstrings would work with the pendulum theme. I'll probably have a check somewhere in the upcoming months on whether I could fix this.

[flying-sheep]

Seems like that plugin could be a simple way to add this.

I fully understand that Sphinx is fiddly while Mkdocs is much easier. Yet I’d be very hesitant to create a Python library without an inventory file for its docs since intersphinx is such a boon.

[flying-sheep]

Seems like mkdocstrings supports this, both as consumer and generator: https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories