Open Stack

Works for me. The api-ref stuff is much easier to maintain, review, and the
resulting docs are infinitely more usable for developers.

I'm already working on getting api-ref up to date; the current docs there
are sorely out of date and wrong. I'd like to land these patches quickly
and iterate on improving them, rather than stall any improvements until
this is perfect.

https://review.openstack.org/312795
https://review.openstack.org/313187
https://review.openstack.org/313708

You can view the results from the build in the new api-ref job, eg. here:
http://docs-draft.openstack.org/08/313708/1/check/gate-ironic-api-ref/5c28efa//api-ref/build/html/

--Deva


On Thu, May 5, 2016 at 6:18 AM Jim Rollenhagen <jim at jimrollenhagen.com>
wrote:

> On Wed, May 04, 2016 at 05:22:05PM -0400, Ruby Loo wrote:
> > Sweet. Thanks Jim (and everyone else that made this happen).
> >
> > I do want to make sure there is one "source of truth" to the API
> > documentation. We are already generating REST API documentation at
> > http://docs.openstack.org/developer/ironic/webapi/v1.html. The info for
> > this comes from docstrings etc in our code files.
> >
> > To make it easier and so that documentation doesn't get out of sync, I
> > don't really want people to have to remember to update the
> code/docstrings
> > as well as the new files that were added to generate this new api-ref
> > documentation.
>
> I agree. I think the first thing we need to do is get the api-ref tree
> up to date. After that, we can refactor the stuff in doc/source/webapi
> to be pointers to the new thing, and drop the API docs from the
> docstrings.
>
> Does that work for everyone?
>
> // jim
>
> > --ruby
> >
> >
> > On Wed, May 4, 2016 at 5:10 PM, Jim Rollenhagen <jim at jimrollenhagen.com>
> > wrote:
> >
> > > Hey y'all,
> > >
> > > I did the push this week to move the api-ref into our tree, and it's
> now
> > > publishing. \o/
> > >
> > > The docs are here: http://developer.openstack.org/api-ref/baremetal/
> > >
> > > The source is here:
> > > http://git.openstack.org/cgit/openstack/ironic/tree/api-ref/source
> > >
> > > I know devananda is doing a push to update some things there. If you'd
> > > like to help clean up and improve our docs, please sync with him. They
> > > need a lot of love, so all help is welcome. :)
> > >
> > > // jim
> > >
> > >
> __________________________________________________________________________
> > > OpenStack Development Mailing List (not for usage questions)
> > > Unsubscribe:
> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> > >
>
> >
> __________________________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe:
> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160509/f214731f/attachment.html>