Open Stack

On 22/02/2019 10:47, Stephen Finucane wrote:
> On Thu, 2019-02-21 at 18:08 +0100, Luigi Toscano wrote:
>> 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.
> I thought the reason we hadn't done this was because the API reference
> was intentionally unversioned, while the of the documentation was not?
> What's changed that we could start moving this in-tree?

Now you say it out loud, I'm fairly certain this is exactly why we 
didn't do it. As per the spec we wrote

for the OS manuals migration, we did "say" we were going to do this 
work. See [4]. Although

the caveat was "... is deferred until we are farther (further, jeez) 
along with the initial migration

work."

I'm not sure if we have any other historical notes on this.


[4] 
https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html 


>
> Stephen
>
>> [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