3 ms·
Hmm, this has not been my experience with Python libraries (I can't speak for JS ones). The vast majority are well-enough documented that I've never had a probl
by StavrosK 8y ago
Hmm, this has not been my experience with Python libraries (I can't speak for JS ones). The vast majority are well-enough documented that I've never had a problem, and I strive to document my important libs at least this well:
https://yeelight.readthedocs.io/ https://yeelight.readthedocs.io/
- wwright 8y agoIt 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