31–34 of 34 posts
Happy to see they pick ReST over MD. ReST is vastly superior for these purposes, in my experience.
Mind explaining why? I like Markdown but would like to know what ReST does better.
Happy to see they pick ReST over MD. ReST is vastly superior for these purposes, in my experience.
Mind explaining why? I like Markdown but would like to know what ReST does better.
Earlier quoted context omitted.
No reason it couldn't be both, I suppose.
Definitely the case in my office. A couple of opinionated and (relatively) senior devs that think the code is the documentation. No, I can't read this 40 yo fortran code and use it as the basis for a new program on a different architecture. It uses gotos and variables like "yxtgn" that mean nothing to the reader (turned out y meant it was an integer, weird). I spent a month on that because there was no documentation,…
It meant "ynteger". Elementary, my dear Watson.
They missed a format that's ubiquitous, has a lot of formatting options, and has search facilities. Manpages. When someone's looking for a piece of documentation, they are usually working on a system as they do it, and man -k is a lot easier to remember than some other search tool that requires its own set of packages, etc.
You can build man pages with Sphinx. http://www.sphinx-doc.org/en/stable/builders.html