Ask HN: What software documentation tools do you use (for JavaScript codebases)?

8 points by jthomerson ↗ HN
We have a half dozen or more git repos, each with a README.md file. Some of those repos contain front-end JS libraries or apps, in which case we use JSDoc to generate the documentation for that repo. Other repos represent a particular system, and contain numerous microservices. Each microservice has its own README.md. We also have other markdown files containing coding standards and other documentation that's not specific to a single project.

We need documentation at several levels: the codebase itself (mostly JSDoc), the individual library or microservice (mostly the README.md explaining that library or service), but then also at a higher-level: how do all the services in this system (repo) tie together and interoperate? Or, in a separate primarily-docs repo: here's our coding standards, official policies on things such as security, etc.

Ideally we'd have a tool that we could run on our CI server that builds docs from each of those repos and exports the docs as a static site. We'd also be able to easily link between services and code across codebases.

I've looked at / tried Sphinx, but since we are primarily JS / Markdown, it would be very different to try to use it for our projects, and the sphinx-js integration was lacking (couldn't really replace our JSDoc builds). I've tried a number of static site generators (e.g. hexo, hugo, etc), but they tend to be more about sites and blogs, and don't seem to work well for documentation.

What do you use?

2 comments

[ 0.24 ms ] story [ 17.5 ms ] thread