<div dir="ltr"><div>Works for me. The api-ref stuff is much easier to maintain, review, and the resulting docs are infinitely more usable for developers.</div><div><br></div>I'm already working on getting api-ref up to date; the current docs there are sorely out of date and wrong. <span style="line-height:1.5">I'd like to land these patches quickly and iterate on improving them, rather than stall any improvements until this is perfect.</span><div><span style="line-height:1.5"><br></span></div><div><a href="https://review.openstack.org/312795">https://review.openstack.org/312795</a> <br></div><div><span style="line-height:1.5"><a href="https://review.openstack.org/313187">https://review.openstack.org/313187</a></span></div><div><a href="https://review.openstack.org/313708">https://review.openstack.org/313708</a><br></div><div><br></div><div>You can view the results from the build in the new api-ref job, eg. here:</div><div><a href="http://docs-draft.openstack.org/08/313708/1/check/gate-ironic-api-ref/5c28efa//api-ref/build/html/">http://docs-draft.openstack.org/08/313708/1/check/gate-ironic-api-ref/5c28efa//api-ref/build/html/</a></div><div><br></div><div>--Deva</div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr">On Thu, May 5, 2016 at 6:18 AM Jim Rollenhagen <<a href="mailto:jim@jimrollenhagen.com">jim@jimrollenhagen.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Wed, May 04, 2016 at 05:22:05PM -0400, Ruby Loo wrote:<br>
> Sweet. Thanks Jim (and everyone else that made this happen).<br>
><br>
> I do want to make sure there is one "source of truth" to the API<br>
> documentation. We are already generating REST API documentation at<br>
> <a href="http://docs.openstack.org/developer/ironic/webapi/v1.html" rel="noreferrer" target="_blank">http://docs.openstack.org/developer/ironic/webapi/v1.html</a>. The info for<br>
> this comes from docstrings etc in our code files.<br>
><br>
> To make it easier and so that documentation doesn't get out of sync, I<br>
> don't really want people to have to remember to update the code/docstrings<br>
> as well as the new files that were added to generate this new api-ref<br>
> documentation.<br>
<br>
I agree. I think the first thing we need to do is get the api-ref tree<br>
up to date. After that, we can refactor the stuff in doc/source/webapi<br>
to be pointers to the new thing, and drop the API docs from the<br>
docstrings.<br>
<br>
Does that work for everyone?<br>
<br>
// jim<br>
<br>
> --ruby<br>
><br>
><br>
> On Wed, May 4, 2016 at 5:10 PM, Jim Rollenhagen <<a href="mailto:jim@jimrollenhagen.com" target="_blank">jim@jimrollenhagen.com</a>><br>
> wrote:<br>
><br>
> > Hey y'all,<br>
> ><br>
> > I did the push this week to move the api-ref into our tree, and it's now<br>
> > publishing. \o/<br>
> ><br>
> > The docs are here: <a href="http://developer.openstack.org/api-ref/baremetal/" rel="noreferrer" target="_blank">http://developer.openstack.org/api-ref/baremetal/</a><br>
> ><br>
> > The source is here:<br>
> > <a href="http://git.openstack.org/cgit/openstack/ironic/tree/api-ref/source" rel="noreferrer" target="_blank">http://git.openstack.org/cgit/openstack/ironic/tree/api-ref/source</a><br>
> ><br>
> > I know devananda is doing a push to update some things there. If you'd<br>
> > like to help clean up and improve our docs, please sync with him. They<br>
> > need a lot of love, so all help is welcome. :)<br>
> ><br>
> > // jim<br>
> ><br>
> > __________________________________________________________________________<br>
> > OpenStack Development Mailing List (not for usage questions)<br>
> > Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> > <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
> ><br>
<br>
> __________________________________________________________________________<br>
> OpenStack Development Mailing List (not for usage questions)<br>
> Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div>