search

paganpasta / eqxvision

A Python package of computer vision models for the Equinox ecosystem.
https://eqxvision.readthedocs.io
MIT License
100 stars 12 forks source link

Need to run `mkdocs` twice. #7

Open patrick-kidger opened 2 years ago

patrick-kidger commented 2 years ago

Super cool to see this project get off the ground!

I just thought I'd give you a heads-up if you're using my doc-building stack, that the mkdocs command needs running twice in order to build the documentation correctly. See for example https://github.com/patrick-kidger/diffrax/blob/77bd28b03aafdebcd985d900118ffb900be66d65/.github/workflows/build_docs.yml#L33

The TL;DR is that the first call is used to populate a cache of "all documented objects", which is used by the second pass to display their names in the documentation in the desired way.

Whether this is possible with ReadTheDocs I don't know.

FWIW I know the underlying mkdocstrings/pytkdocs stack is being reworked quite substantially, so another approach that may be possible is to rewrite my custom ~hacks~ tweaks to fit the new world order. (I've not looked into this at all -- right now I'm just using pinned versions of mkdocstrings+pytkdocs and was planning to figure this out only if something eventually breaks.)

paganpasta commented 2 years ago

Thanks for the info! I completely forgot about the double build which I initially saw on the Equinox contributing guidelines.