Hi, A quick update on status and current direction for the blueprint api-doc-in-trunk<https://blueprints.launchpad.net/quantum/+spec/api-doc-in-trunk>. There is a branch attached to the blueprint; this branch currently contains a skeleton for RST documents which should be used for developer documentation. I'm currently generating documents with Sphynx 1.0.7 .
I think you all followed the discussion on the Openstack mailing list concerning separation of code and specification, and where the documentation should reside. A lot of very valid argument have been proposed, even if no agreement has still been reached. Nevertheless, the need for allowing the core team to control not just the API code, but also its specification, is quite clear. For Quantum, we used the Openstack Wiki for tracking the API specification. Although the Wiki is a good tool for collaboration, it has no review process; and this has been a serious limit. For this reason, I think it would be good for use to start moving the API specification in the source code tree, even if other projects, such as Keystone, decided to take it out of it (it seems it's going to be moved into Openstack-manuals project) As regards the format, all the other projects are using DocBook for API specification, and RST for man pages and other documentation. It is my opinion we should be consistent with the other projects, even if reviewing DocBook XML is not going to be really pleasant. For an example, have a look at the OS compute dev guide<http://bazaar.launchpad.net/~annegentle/openstack-manuals/trunk/view/head:/doc/source/docbkx/openstack-compute-api-1.1/os-compute-devguide.xml>. Another argument being discussed in the Openstack Mailing List is whether API specification should be generated straight from code (i.e.: docstrings) or kept separate. I have to admit I don't have a strong opinion on this point. You can go to the Openstack Mailing List and follow the "architect vs developer" discussion; however, I totally agree with the people who commented that actually the most important recipient of the API specification are the users. This leads me to think that what we probably should do for Quantum is to move the API specification in the source code tree, but keep it separate from the code, in order to not clutter it with implementation-level details, which make sense to developers but not to users of the API. Your feedback is, as always, more than welcome. Best regards, Salvatore
-- Mailing list: https://launchpad.net/~netstack Post to : netstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~netstack More help : https://help.launchpad.net/ListHelp
