Hacker News Reader

Comment by wdfx | Hacker News Reader

I think it is unfair that the article says there is only one other contender.

There exists for example esdoc [1] which is capable of compiling together written documents with generated documentation. I've just implemented this for two work projects with the return of many thanks from my team.

That said I will also check out sphinx-js because we also maintain python projects and already use sphinx for those.

[1] https://github.com/esdoc/esdoc

View on HN

Author here. I just learned about esdoc this morning; thanks for mentioning it! But it doesn't appear to be much of an improvement over JSDoc for my purposes, as you still get little control over the organization of your content. It is alphabetical reference docs plus a few predefined bolt-on pages (https://esdoc.org/#integration-manual):

    Overview
    Design
    Installation
    Usage
    Tutorial
    Configuration
    Example
    Advanced
    FAQ
    Changelog

You can't add more. And, as far as I can tell (the documentation I can find is silent on the point), those pages are islands, with no ability to call content out of the code. (I'd love to be shown wrong. Did you find otherwise?) However, I do applaud esdoc's better support for more modern JS features!

Some of your assumptions are incorrect. Those names you list are documentation categories, under which you can publish any pages in your own order. The final docs do not actually display those category names, but some have different menu colours by default.

You can also link between written docs and API docs, though it is a bit manual/hacky (you need to know the rendered file paths).

Thanks for clearing that up!

Dgeni has been around for years and (is?) has been used to document the Angular codebase.

Reply on news.ycombinator.com