[docs] Publish `objects.inv` for intersphinx linking

[webknjaz]

Motivation: I want to link these docs from PyPUG.

I'm not familiar w/ mkdocs but it looks like one of these is the way:

• https://pypi.org/p/mkdocs-intersphinx
• https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories

[agriyakhetarpal]

Hi @webknjaz, that's a great idea – thanks! I hope you don't mind if I mark this with a "good first issue" label 😉

[henryiii]

With the slow collapse of MkDocs, this also could be a good point to look at alternatives?

[agriyakhetarpal]

Agreed, I would be happy to move to Zensical if it satisfies our requirements. But I can't immediately find if it supports intersphinx, because it doesn't have proper support for more popular plugins alone: https://zensical.org/compatibility/plugins. Maybe ProperDocs?

[omkar-334]

hi @agriyakhetarpal can i work on this issue

[agriyakhetarpal]

Hi @omkar-334, yes, please feel free to work on this issue. I would also recommend reading the linked blog post and about the other projects that have emerged, so you can get a clear sense of what's happening in the world of MkDocs. 🙂 We can create a dedicated issue to think about migrating to Zensical/ProperDocs/etc, of course.

[omkar-334]

Hi @omkar-334, yes, please feel free to work on this issue. I would also recommend reading the linked blog post and about the other projects that have emerged, so you can get a clear sense of what's happening in the world of MkDocs. 🙂 We can create a dedicated issue to think about migrating to Zensical/ProperDocs/etc, of course.

yes, i will get started by reading the blog posts. I do have experience with MkDocs, but will check the current happenings

[henryiii]

What about using sphinx + myst-parser? That does support plugins (there's a good one for color ANSI codes that I contributed to) that matches one of our custom plugin(s?)). It's also pretty stable, has excellent support for intersphinx, and the furo theme is excellent and clean. It's also the only other one to have native readthedocs support (all the new mkdocs replacements do not). Also great support for man pages and such. Main downside is that it's slower.

I'm checking into the maintenance of those to make sure there are no issues, but I think it's in better shape than the MkDocs-likes.

[agriyakhetarpal]

I am on board with using Sphinx + MyST-Parser. My only reason for not suggesting it so far was that I wasn't sure of the rootings of our decisions to use MkDocs and whether we'd want to switch away from it. :) One of MkDocs' premises is speed, but it may not be so bad with Sphinx. We'd go from our current ~2 seconds to ~30 at most, maybe. There are some concerns with MyST-Parser's maintenance, yes, but it's better than our status quo.

[Czaki]

If I correctly remember, the main argument was complexity of documentation source files (rst). So with myst-parse this problem should not be present.

[joerick]

Let's take the question of future docs frameworks to a new issue... it's a much bigger question and the 'good first issue' tag might not apply :)

My feeling on the initial question would be just to use URLs :) I am a big believer in durable URLs and I try not to move anything in the docs without ensuring a redirect is in place. I did have a look at the mkdocs-intersphinx extension and it requires tagging headers like this-

# My Page

<!-- ref:important-section -->
## Important Section

This section can be referenced by other projects.

<!-- ref:another-topic -->
### Another Topic

More content...

Which is something we already do, just with HTML id tags, which in our flavour of markdown look like this:

### `manylinux-*-image`, `musllinux-*-image` {: #linux-image env-var toml}

#linux-image is the id, the env-var toml bit applies classes which are used by javascript. That means this option's URL is https://cibuildwheel.pypa.io/en/stable/options/#linux-image .