REST API doc is not auto-generated

[aeva black]

Our REST API spec / doc is hand-written and therefor perpetually out of date.

Ceilometer is auto-generating their REST API docs from the pecan/wsme code directly. We should be doing the same.

[Haomeng,Wang (whaom)]

In technical, pytnon API document can be auto-generated, I will check with Ceilometer guys to see how to do, and what is the steps.

[Haomeng,Wang (whaom)]

Ceilometer use https://git.openstack.org/cgit/stackforge/sphinxcontrib-docbookrestapi/ to create API doc, will try this for our Ironic.

[Haomeng,Wang (whaom)]

sphinxcontrib-docbookrestapi is just a extension for Sphinx for our OpenStack RestAPI document generator, so we have to install Sphinx first then enable sphinxcontrib-docbookrestapi to create our Ironic API doc.

[Haomeng,Wang (whaom)]

Sphinx extension sphinxcontrib-docbookrestapi that generates documentation for api-site from RST files.

[Haomeng,Wang (whaom)]

So I think once our RST file is ready, it can be used for our Community to publish these RST to api-site, such as the official Nova-API document - http://docs.openstack.org/api/openstack-compute/2/content/.
I understand for our Ironic, we just make sure the RST is ready once we want to integrated to OpenStack as new core project, then the api-site owner who can help us take our Ironic RST file as input and run Sphinx with sphinxcontrib-docbookrestapi extension to auto-generated our official Ironic API documents, any comments?

[Haomeng,Wang (whaom)]

And for our Ironic wiki's internal API documents, we can run "python setup.py build_sphinx" to generate the API documents.

[Haomeng,Wang (whaom)]

FYI - this is a api doc which created by sphinxcontrib-docbookrestapi I think - http://api.openstack.org/api-ref-compute.html

[Haomeng,Wang (whaom)]

Devananda, I found the root cause, because our code can not pass the Sphinx validations, will encountered a lot of "NameError: name '_' is not defined" error, so all these py file which has such issue, the documents can not be generated by Sphinx. And I checked Ceilometer code, for each py which use "_()" for i18n, it will import _ from gettextutils, that is the way to void such issue during our document creating by Sphinx, will try to fix.

In summary, we have to documents:
1. missing some document in - http://docs.openstack.org/developer/ironic/py-modindex.html, such as the apis under controllers/v1
2. We need sphinxcontrib-docbookrestapi to generate the REST API, like these nova api documents - http://api.openstack.org/api-ref-compute.html

So we missed a lot of documents, need to fix these issue.

[Haomeng,Wang (whaom)]

Based on current python code, we will missing all ironic.api.controllers.v1.* objects in this document -
http://docs.openstack.org/developer/ironic/py-modindex.htm, Devananda, would you please help to review the patch.
I

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/56605

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/56605
Committed: http://github.com/openstack/ironic/commit/92a9c5094c7d472a0b53fdb78de5b1f3da25a079
Submitter: Jenkins
Branch: master

commit 92a9c5094c7d472a0b53fdb78de5b1f3da25a079
Author: Haomeng, Wang <email address hidden>
Date: Tue Nov 19 08:15:25 2013 +0800

    Import missing gettext _ to fix Sphinx error

    We run "python setup.py build_sphinx" to generate the API documents,
    however encountered a lot of "NameError: name '_' is not defined",
    which will cause our api.controllers.v1.* objects documents will not
    be generated by Sphinx, so we are missing these in the document page
    http://docs.openstack.org/developer/ironic/py-modindex.html. Import
    missing gettext _ to fix such Sphinx error with this patch.

    Change-Id: Ie53d96203109b8b95b9734b58d85da41a2d011cf
    Closes-Bug: #1251011

[aeva black (tenbrae)]

Review 56605 fixed an important issue, but did not actually address this bug. I am reopening it.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/57346
Committed: http://github.com/openstack/ironic/commit/30206795b71d9b53c586385fe235d588bfe70a44
Submitter: Jenkins
Branch: master

commit 30206795b71d9b53c586385fe235d588bfe70a44
Author: Devananda van der Veen <email address hidden>
Date: Tue Nov 19 15:21:45 2013 -0800

    Add hooks to auto-generate REST API docs

    Add the necessary bits for sphinxcontrib-pecanwsme
    so that we can start auto-generating REST API docs.

    Change-Id: I6ad61a5185462916865884dd1619465ef90aba0a
    Closes-bug: 1251011