A conversation with @xiuqin and @gpdf reaffirmed that we need to start planning how to deliver developer documentation for Firefly.
The core foundation of our documentation work is Sphinx. I think there’s value in choosing one tool for all of our doc projects because I can invest in building toolchains and good web design. Sphinx of course works out of the box for Python API documentation, and I’m working towards a firm vision of how C++ APIs are built with Sphinx as well.
How to document JavaScript APIs has been completely un-specified, hence this discussion now.
The zeroth option is that JavaScript APIs be documented completely independently of the code. Sphinx allows you to markup JavaScript APIs in reStructuredText. This is the least intrusive option for the existing JS code. However, I think it’s not ideal because then the API doc and API implementation would live in separate files.
More realistically, I think we want to annotate the JavaScript code so that docs live in the code, and those docs are extracted for presentation on the web in a developer guide. There are a lot of good JavaScript documentation standards out there: JSDoc, YUIDoc, docco, doxx, even doxygen, I think. This article compares and contrasts these tools: http://blog.fusioncharts.com/2013/12/jsdoc-vs-yuidoc-vs-doxx-vs-docco-choosing-a-javascript-documentation-generator/ The author chooses JSDoc in the end.
The good new is that JSDoc and YUIDoc both have JSON export options. Rather than building HTML documentation, these tools can simply export their parsed API database. This API dataset could then be ingested into Sphinx and rendered into reStructuredText and Sphinx’s HTML output.
I’ve looked and there doesn’t seem to be any existing Sphinx extensions that parse JSDoc/YUIDoc JSON output. There is a Sphinx extension for an older version of JSDoc. That said, it’s likely something that I can build.
So what I want to know from the JavaScript developers is
- Do you have a preference between the doc syntax of JSDoc, YUIDoc or something else?
- Is there a different JavaScript documentation workflow entirely that you’d prefer?