-
-
Notifications
You must be signed in to change notification settings - Fork 102
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: Allow linking to an identifier not only by its exact anchor #217
Conversation
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.