Add default_role for Sphinx. #571
Conversation
Fix a bunch of broken refs along the way, which become errors now via -W if you have default_role set. In theory you can catch those via sphinx-build -n (i.e. nitpick mode), which IMHO is a decent idea anyhow, but it's a longer diff to enable that because it'd involve fixing a bunch of the places that try to reference types that don't exist (e.g. :type foo: Any value). But obviously can be done. Also didn't actually use this anywhere yet (the any role), but will do so in a follow-up if this is acceptable.
|
OK and now I just used this for a bunch of builtin refs just to show you how it looks. I can keep going, but actually there are some more broken refs hiding that don't become errors without Line 207 in f84f451 NotCallableError), which doesn't seem like it's included in any document, but that doesn't raise an error without having nitpick mode turned on unless you try to any-role-ref it.
|
|
That looks cool overall. If we go that way it should definitely pass in nitpick mode if it's possible at all. |
Enables the link to z.i.Interface.
Fix the remaining broken links or whitelist them via nitpick_ignore.
Except one, that probably meant :func:, and which is a duplicate ref.
|
OK done. And looks like there weren't very many more broken references after the first few, so that's good, was fairly easy. So nitpick mode is enabled -- I use the most "conservative" way to handle non-types being mentioned as types myself -- which is basically from now on you literally need to whitelist those in Sphinx's config. IMO this is the right idea considering just how easy it is to get Sphinx to silently not link a reference (as you saw without -n :/) but there are some other ways to do this if you don't like this one. (Sphinx will though error if the default_role finds multiple possible targets, so if you accidentally have a doc and a type named the same thing or whatever, you're still fine in that you'll get a non-silent failure.) |
|
Cool, TIL, thanks! |
(Mentioned in #568 (comment))
Fix a bunch of broken refs along the way, which become
errors now via -W if you have default_role set.
In theory you can catch those via sphinx-build -n (i.e.
nitpick mode), which IMHO is a decent idea anyhow, but it's
a longer diff to enable that because it'd involve fixing a
bunch of the places that try to reference types that don't
exist (e.g. :type foo: Any value). But obviously can be done.
Also didn't actually use this anywhere yet (the any role),
but will do so in a follow-up if this is acceptable.
But throwing the PR up as-is just to show what I meant / see if it's something we want.
Pull Request Check List
This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. But please read our contribution guide at least once, it will save you unnecessary review cycles!
If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.
.pyi).tests/typing_example.py.docs/api.rstby hand.@attr.s()have to be added by hand too.versionadded,versionchanged, ordeprecateddirectives..rstfiles is written using semantic newlines.changelog.d.If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!