feat: Allow linking to an identifier not only by its exact anchor #217
Conversation
oprypin
force-pushed
the
anylink
branch
2 times, most recently
from
c8d15aa
to
39d77f8
Compare
|
...but also by? 😄 I'm not sure to get the change here. Basically the URL map is moved into the Handlers instance, with a method to register an anchor, and a method to get an anchor from a collected item, overwritable in each handler. 👍 Then when fixing cross-references, we search if we have a registered anchor for a given identifier, and if we do not, we try to collect the item through each handler to compute the anchor? I'd like to discuss the case when the anchor is not already registered. The case happens when someone cross-references an object that was not injected in the docs (it was not collected nor rendered). Then how force-collecting it to get its anchor would be useful, as the object is still not rendered in any page? I think I'm missing something 😄 |
|
The slight mistake in your description is the part about "force-collecting". No such thing is happening, and the object's "linkability" is not affected. The use case for me: an object has its very strict "canonical" anchor but |
because even if the collector returns an anchor and that anchor doesn't exist, the behavior will be exactly the same as without this change |
|
Oh okay I see now. Your change allows to do something like this: # pkg/a.py
from pkg.b import Kls# pkg/b.py
class Kls:
...Inject object:
::: pkg.a:Kls
Cross-reference it (in markdown directly or in docstrings),
both are equivalent:
- [my kls][pkg.a.Kls]
- [my kls][pkg.b.Kls] |
|
Did a force push because it contained a commit that was merged elsewhere. |
|
Oh I think you're right in your comment. So then, it fixes #178 (comment) :D I already forgot |
|
Well I'd say it's a workaround for #178 and not a full fix, for the following reason: if you import a class from a private module in a module above it, it's because you want to make it public there. Therefore you want that class to use its public path as canonical, not its real path, otherwise it defeats a bit the purpose of documenting your API (and it's the current behavior, that I think is wrong, in pytkdocs). Imagine telling users to inherit from Anyway, not much to do with this PR, I'm mainly commenting on #178 😅 |
|
Regressions run shows nothing newly broken https://github.com/oprypin/mkdocstrings-regressions/actions/runs/491976653 |
|
OK, LGTM! Would you also like to update the docs to document this new feature (and its limitation when names clash)? If not, I can do it of course, but not sure when! |
|
OK, added the docs :D |
|
Passing a callable, heh, OK with me 🙂 |
No description provided.