HN Explorer

Ask HN: How do you generate documentation?

4 points by adam_ellsworth ↗ HN
It seems there's a new Open Source documentation generator project out there pretty regularly and I'm sure a litany of paid services to manage better docs. In the past we've used lots of different tools from jsdoc parsers to stoplight; however we're in the need for a new solution that can work well for a very small team.

Primarily looking for:

- API Docs - SDK Docs - Code structure docs (beyond tests and codecoverage)

4 comments

[ 2.5 ms ] story [ 21.8 ms ] thread
ddavis
Sphinx is very nice to work with, and it's been around for a long time. I've used it for Python projects, C++ projects (with doxygen and breathe), and some programming language agnostic things. It's almost trivial to pair Sphinx docs with readthedocs.org as well. For smaller pieces of documentation (and many personal things) I use Org mode in Emacs. Org mode supports exporting to a wide variety of formats.
stanpinte
We use Sphinx extensively in our organization, as it's text based (works nicely with GIT) and extensible (we can add the necessary directives to support domain specific documentation requirements from CENELEC standards).

Our product is a railway signalling onboard system.

edoceo
I'm using OpenAPI, Doxygen and Asciidoctor. We also have Phabrixator for internal wiki and project tools
simonblack
After sweating drops of blood through my forehead and recording the results with Libre Office, I then export it to PDF.

I've tried super-duper generators in the past. They never seem to give you results that are worth the effort and time spent.