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.
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.
If devs are happy with JSDoc, then it may be simple to incorporate JavaScript APIs into our docs.
Update: I spoke too soon: the Safari Books code note in their README that
The RST-Template library for creating reST files from JSDoc comments currently uses jsdoc-toolkit, which is no longer in active development. If we decide that its successor JSDoc 3 has enough useful improvements, we can look into updating the library to use that instead.
I’d feel uncomfortable creating a workflow based on deprecated projects, so it would still be worth building a Sphinx extension for JSDoc 3.
We have doing our code documentation with JSDoc mostly because we don’t have any better alternatives. Do you have a link that show the difference between jsdocs and jsdocs3?
Right now I have no interest in YUIDoc, mostly because I perceive YUI as dying.
As to question 2, that is where it gets harder. I think much of our external facing documentation needs to be much more that API docs like JSDoc or JSDoc3 would provide. We need a lot of how to and example docs that does not need to sit in the code. That is why we are using markdown on GitHub (see firefly/docs on github). That is where my greater concern is.
I’m 100% on board with that. Sphinx, a documentation tool, facilitates making a full spectrum of documentation, from user guides and tutorials through to API references. Take the Astropy docs as a vision of where I want to take Stack documentation. It’s a website that has a combination of high-level documents, tutorials, and then API sections that themselves are combinations of high-level overviews, tutorials, in depth guides, and finally the API reference.
In other words, in the new doc platform we’d be able to round up the existing markdown you have in firefly/docs/ and combine it cohesively with an API reference extracted from code.
So the trick is just making sure that JSDoc3 is the tool/syntax we want to build JS API references in. And it seems that the answer is yes?
There’s a new JSDoc-syntax compatible JS documentation builder: documentation.js (on GitHub).
The nice thing about this is that we can keep the JSDoc syntax, but use what seems like a more modern and healthier build tool. It exports to HTML, Markdown and JSON. The JSON export would let me interface it with Sphinx.