4 ms·
It always amazes me that the Python community is okay just missing indices for their API documentation. I’m so used to Rust [1], MDN [2], Apple [3], Qt [4] star
by wwright 8y ago
It always amazes me that the Python community is okay just missing indices for their API documentation. I’m so used to Rust [1], MDN [2], Apple [3], Qt [4] starting their docs off with great indices. Obviously, those are all “commercial” docs, but just indices alone is a huge help.
To be clear, I think you’ve done an absolutely great job writing the prose — I just don’t get the cultural conventions around Readthedocs :p
(There’s still wild differences in quality between those four. It seems like documentation UX would be more of a solved problem by now.)
[1]: https://docs.rs/reqwest/0.9.15/reqwest/#structs https://docs.rs/reqwest/0.9.15/reqwest/#structs
[2]: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_...
[3]: https://developer.apple.com/documentation/corevideo https://developer.apple.com/documentation/corevideo
[4]: https://doc.qt.io/qt-5/qtwebengine-index.html https://doc.qt.io/qt-5/qtwebengine-index.html
- StavrosK 8y agoWhat do you mean by index? This is what I think of when I hear "index": https://yeelight.readthedocs.io/en/latest/yeelight.html https://yeelight.readthedocs.io/en/latest/yeelight.html Rust does the same, as far as I've seen (although the docs are a bit too index-heavy). Do you mean something different?
- mjw1007 8y agoMaybe they mean something more like this page https://yeelight.readthedocs.io/en/latest/genindex.html https://yeelight.readthedocs.io/en/latest/genindex.html which your Sphinx setup appears to be generating but the theme doesn't seem to be linking to.
- StavrosK 8y agoOh, thank you, that is extremely useful to include. Too bad Sphinx doesn't make these things easy, I spent some time reading the docs to figure out how to include a link to the index and there was no reference to it. In the end, this Stack Overflow answer was the only thing I found that actually mentioned how to create it: https://stackoverflow.com/a/42310803/28196 https://stackoverflow.com/a/42310803/28196
- mjw1007 8y agoThe default theme adds a link to it for you in the header and footer. I'm not sure why some other themes don't.
- wwright 8y agoThis is exactly what I was thinking of. Thanks for pointing this out, and thanks to Stavros for promptly engaging too :-)
- inglor 8y agoMDN is a wiki though, run by a nonprofit and written by the community.
- wwright 8y agoYes, but it’s backed by enough interests and money that it’s still not fair to compare to a typical FOSS or hobby project :p