Open Stack

Hi all,

During the last PTG it was decided to move forward with the migration of the 
api-ref documentation together with the rest of the documentation [1].
This is one of the item still open after the (not so recent anymore) massive 
documentation restructuring [2].

(most likely anything below applies to releasenotes/ as well.)

I asked about this item few weeks ago on the documentation channels. So far no 
one seems against moving forward with this, but, you know, resources 
:)

I think that the process itself shouldn't be too complicated on the technical 
side, but more on the definition of the desired outcome. I can help with the 
technical part (the moving), but it would be better if someone from the doc 
team with the required knowledge and background on the doc process would start 
with at least a draft of a spec, which can be used to start the discussion.


If implemented, this change would also fix an inconsistency in the guidelines 
[2]: the content of reference/ seems to overlap with the content of api-
ref("Library projects should place their automatically generated class 
documentation here."), but then having api-ref there would allow us to always 
use api-ref. That's where the entire discussion started in the QA session [3]: 
some client libraries document their API in different places.


[1] https://etherpad.openstack.org/p/docs-i18n-ptg-stein line 144
[2] https://docs.openstack.org/doc-contrib-guide/project-guides.html
[3] https://etherpad.openstack.org/p/clean-up-the-tempest-documentation


Ciao
-- 
Luigi