-
-
Notifications
You must be signed in to change notification settings - Fork 52
-
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?
Beta Was this translation helpful? Give feedback.
All reactions
Replies: 1 comment 5 replies
-
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 🙂
Beta Was this translation helpful? Give feedback.
All reactions
-
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.
Beta Was this translation helpful? Give feedback.
All reactions
-
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 🙂
Beta Was this translation helpful? Give feedback.
All reactions
-
That's too bad 😞 , but how impossible is it?
Beta Was this translation helpful? Give feedback.
All reactions
-
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 🙂
Beta Was this translation helpful? Give feedback.
All reactions
-
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...
Beta Was this translation helpful? Give feedback.
All reactions
-
👍 1 -
❤️ 1