Ask HN: What are your favorite tools for generating simple documentation? | Hacker News Reader

Ask HN: What are your favorite tools for generating simple documentation?

11 pointsnagonago6 comments

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?

View on HN

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.

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 like

https://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

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

Hugo with the Docsy theme.

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.

ASCIIDoc

Reply on news.ycombinator.com