Open Stack

---- On Sat, 23 Feb 2019 00:14:41 +0900 Doug Hellmann <doug at doughellmann.com> wrote ---- 
 > Luigi Toscano <ltoscano at redhat.com> writes: 
 >  
 > > On Thursday, 21 February 2019 19:45:53 CET Doug Hellmann wrote: 
 > >> Luigi Toscano <ltoscano at redhat.com> writes: 
 > >> > On Thursday, 21 February 2019 18:34:03 CET Sean McGinnis wrote: 
 > >> >> On Thu, Feb 21, 2019 at 06:08:15PM +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]. 
 > >> >>  
 > >> >> How is this going to work with the publishing of these separate content 
 > >> >> types to different locations? 
 > >> >  
 > >> > I can just guess, as this is a work in progress and I don't know about 
 > >> > most of the previous discussions. 
 > >> >  
 > >> > The publishing job is just code and can be adapted to publish two (three) 
 > >> > subtrees to different places, or exclude some directories. 
 > >> > The global index files from doc/source do not necessarily need to include 
 > >> > all the index files of the subdirectories, so that shouldn't be a 
 > >> > problem. 
 > >> >  
 > >> > Do you have a specific concern that it may difficult to address? 
 > >>  
 > >> Sphinx is really expecting to build a complete output set that is used 
 > >> together. Several things may break. It connects the output files 
 > >> together with "next" and "previous" navigation links, for one. It uses 
 > >> relative links to resources like CSS and JS files that will be in a 
 > >> different place if /some/deep/path/to/index.html becomes /index.html or 
 > >> vice versa. 
 > >>  
 > >> What is the motivation for changing how the API documentation is built 
 > >> and published? 
 > > 
 > > 
 > > I guess that a bit of context is required (Ghanshyam, Petr, please correct me  
 > > if I forgot anything). 
 > > 
 > > During the last PTG we had a QA session focused on documentation and its  
 > > restructuring (see the already mentioned [1]) One of the point discussed was  
 > > the location of the generated API. Right now tempest uses doc/source/library,  
 > > which is not a place documented by the [2]. 
 > > I was arguing about the usage of reference/ instead (which is used by various  
 > > python-<foo>client) and we couldn't come to an agreement. So we asked the Doc  
 > > representative about this and Petr Kovar kindly chimed in. 
 > > 
 > > I don't remember exactly how we ended up on api-ref, but I think that the idea  
 > > was that api-ref, moved to doc/source/, could have solved the problem, giving  
 > > the proper place for this kind of content. 
 > > Then we forgot about this, but fixing the Tempest documentation was still on  
 > > the list, so I asked again on the doc channels and as suggested I have sent  
 > > the email that started this thread. 
 > > 
 > > This is to say that I'm not particularly attached to this change, but I only  
 > > tried to push it forward because it was the suggested solution of another  
 > > problem. I'm more than happy to not have to do more work - but then I'd really  
 > > appreciate a solution to the original problem. 
 >  
 > If this is internal API documentation, like for using Python libraries, 
 > use the reference directory as the spec says. The api-ref stuff is for 
 > the REST API. Some projects have both, so we do not want to mix them. 

Yeah, it was REST API vs internal API (or stable external interface for cross projects usage)
Tempest publish its external stable interface under doc/source/library[1] as we call it more library
interfaces than API but we can move it under consistent path if we do have any.

To be honest, reference/ does not sound good to me for such external (or we call them internal to openstack)
stable interface because reference/ is being used as internal contribution documentation or some history
reference by the projects, so it was confusing for me that anything goes under reference/ is just internal
reference document for new contributor or for history ref or is it for the stable interface (anything
other than REST API) exposed by that project. 

[1] https://docs.openstack.org/tempest/latest/library.html 

-gmann

 >  
 > > [1] https://etherpad.openstack.org/p/clean-up-the-tempest-documentation 
 > > [2] https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html 
 > > 
 > > Ciao 
 > > --  
 > > Luigi 
 > > 
 > > 
 > > 
 >  
 > --  
 > Doug 
 >