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.<p>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?
I have used docfx, sphinx (rst) and tried vite press.<p>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)<p>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.<p>Using vitepress (for writing)and docfx (for publishing) didn’t work due to their subtle differences.<p>My recommendation would be using vitepress, as it makes editing easier and you really want this part to be as much frictionless as possible.<p>And do not go with sphinx as it requires restructuredText. Rst is good, but it introduces a learning curve.
<a href="https://gohugo.io" rel="nofollow">https://gohugo.io</a> 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<p><a href="https://github.com/hofstadter-io/cuetorials.com">https://github.com/hofstadter-io/cuetorials.com</a> 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 (<a href="https://squidfunk.github.io/mkdocs-material/" rel="nofollow">https://squidfunk.github.io/mkdocs-material/</a>). Fits all my requirements nicely.
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.