Cross referencing vs sphinx

[AntoineD]

Hello,

the project I work for is in the process of converting its documentation from sphinx to mkdocs.
We make use of the very convenient reference target specification and resolution of sphinx.

We have tried this plugin but it is not on par with sphinx's related powerful simplicity and features.

We are considering sponsoring mkdocstring to get access to relative and scoped cross-referencing features, but we wonder how it compares to sphinx features.

Would it be possible to have clarifications on these?

[pawamoy]

The ~ prefix is not supported, but scoped cross-references make it superfluous in most cases. Relative cross-refs (with a . prefix seem to resolve the same way as in Sphinx. One thing I noticed could be improved is that [..render][] will display a link with ..render as title instead of render (dots not stripped). One can always re-specify the title anyway: [render][..render].

If you show me how you use Sphinx cross-refs I can show you equivalent in mkdocstrings/autorefs 🙂

[AntoineD]

Basically with sphinx, wherever an entity is located, using .entity will be resolved when there is no ambiguity. This reference can be used in docstrings and anywhere in the docs.
Ambiguities can be resolved by adding context .Context.entity, like .Class.method for instance. We never need to figure out where the target is relatively to where the reference is created.

[pawamoy]

This is not possible with mkdocstrings. But you'll be able to see for yourself in the next days: I'm about to release every private feature to the public 🙂

[AntoineD]

That's too bad 😞 , but how impossible is it?

[pawamoy]

Oh it's definitely doable. You could open a feature request but I can't guarantee I'll be working on it since my priorities have shifted towards Zensical rather than MkDocs 🙂

[AntoineD]

OK so there is hope, I'll try to do it myself.

Congrats for this new promising project!
I'll keep an eye on it...