Open story645 opened 8 months ago
Looks like a good start! It seems like this is probably Sphinx's recommended way of doing things like our tags index page.
Since that would be a breaking change, though, it would be good to support both the new domain and the original tags
directive for awhile, and show DeprecationWarning
for the latter. And then maybe remove that later on after a major version bump?
One way to do this would be:
__init__.py
from 1.3.1 to a separate module, say _compat.py
setup()
from that modulewarnings.warn(DeprecationWarning)
to update_tags()
__init__.py
something like:
from _compat import TagLinks as TagLinksDirective
from _compat import update_tags as update_tags_directive
...
def setup(app): ... app.connect("builder-inited", update_tags_directive) app.add_directive("tags", TagLinksDirective) app.add_domain(TagDomain)
Alternatively, we could also do something simple but terrible like a `str.replace("tags::", "tag:tags::")` on the whole document before it's parsed 😬
Alternatively, we could also do something simple but terrible like a str.replace("tags::", "tag:tags::") on the whole document before it's parsed 😬
I think there's also the https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-primary_domain but yeah that would be not great either, though now I'm thinking if basically in run could call out to the domain version 🤔
So this is busted at the moment, but trying to shake out if it's worth it. Downside of domains is (if you don't use the
primary_domain
config) is that the tag becomestag:tags::
or the like. Upside is I think it makes stuff like #66 easier b/c it's another directive in the domain and has access to the same shared list. Also if I can get this working, thentag_1
etc becomes the cross reference.