What are your favorite tools for generating simple documentation?

Question

I need to write some pretty simple documentation, just a general overview of a code base's structure, installation requirements, and usage. I'm leaning toward just putting everything in a README markdown file, but I might want to expand it a bit more eventually, and it would also be nice to have a static HTML file I could hand over to a team which may not have a markdown reader.I've been looking at different documentation generators, and getting a little overwhelmed by all the options. Maybe I just need a markdown-to-html converter? What is your favorite way to write simple documentation?

rk06 · Accepted Answer

I have used docfx, sphinx (rst) and tried vite press.
I picked sphinx at old job because we had very good infra for it. Even though I found it slow (due to it being python based and my company’s idiosyncrasies)
For my current job, I picked docfx because other people used them and have set up infra for them. I preferred vite press because editing experience was way better with its HMR. However, I couldn’t change the company infra, so docfx it is.
Using vitepress (for writing)and docfx (for publishing) didn’t work due to their subtle differences.
My recommendation would be using vitepress, as it makes editing easier and you really want this part to be as much frictionless as possible.
And do not go with sphinx as it requires restructuredText. Rst is good, but it introduces a learning curve.

verdverm · Answer

https://gohugo.io which supports writing in multiple common formats (asciidoc, markdown, ...) and generates a static html website. You can of course add javascript or frameworks if you likehttps://github.com/hofstadter-io/cuetorials.com is one of the sites I maintain using Hugo. It started as the Docsy theme, but needed to be changed due to limitations

nagonago · Answer

Thanks to everyone who commented. I ended up using Material for MkDocs (https://squidfunk.github.io/mkdocs-material/). Fits all my requirements nicely.

farmin · Answer

Hugo with the Docsy theme.

type0 · Answer

Asciidoctor with a couple of shell scripts or a Makefile, ability to tag your code inclusion makes maintaining your docs simple and hassle free even during re-factoring.

diceduckmonk · Answer

ASCIIDoc