Ceph » mgr » Dashboard

Courtney Caldwell wrote:

Looking at SwaggerHub as publishing method or ReadTheDocs.

We could do both, just to make sure we have broader coverage. The thing that concerns me a bit is that we'd be adding yet another dependency on some third party service that actually would like us to pay money for this and may retract their free tier at any time.

Note that the Ceph documentation is already on RTD: https://ceph.readthedocs.io/ - how about publishing it via https://ceph.readthedocs.io/api/ there?

The RTD method does look like the best idea; however, it seems most projects to link sphinx (our current generation method) and swagger/OpenAPI are older than the v3.0 specification of OpenAPI; I'm going to try importing a package that seems to be simple enough to implement that takes the input YAML/JSON from Swagger and builds out a Sphinx-doc.

If anyone knows of a modern python module that interfaces Swagger's output (which is what we currently use for API documentation) to Sphinx (modern being more recent than late 2017, or specifically referencing OpenAPI 3.0), feel free to share.

https://sphinxcontrib-openapi.readthedocs.io/ is what I'm testing now.

Also, worth noting is we send the docs directly to a CherryPy server, rather than generating the json file seperately (as noted in mgr/dashboard/modules/docs.py); it's passed as a large HTML string to the CherryPy serverlet.

This is efficient as far as avoiding some overhead, but inadequate for static generation: perhaps generating the json file during a build would be better, and having cherrypy call on it. -- looking into possible work-arounds since we need a static json to generate the sphinx-based documentation.