alt Hacker NewsI've never understood why people even _generate_ from the docs folder. If you've written it in markdown (which they nearly always do) then it's already rendered properly in Github. Or is it because they then publish those docs somewhere else?
Replies
WCSTombs • today at 6:52 PM
> Or is it because they then publish those docs somewhere else?
Exactly, I use Sphinx to make a nice website from the markdown sources (although it doesn't have to be markdown). That includes generating a full API reference page from all the docstrings.
I think generation helps with content and structure that GitHub Markdown does not support, as well as having a dedicated (and brandable) website.
An example:
- source: https://github.com/eslint/eslint/blob/main/docs/src/rules/no...
- rendered: https://eslint.org/docs/latest/rules/no-control-regex
This is a very simple example, you can see how the code blocks are highlighted better and slightly interactive.