Open Stack

On Fri, 2019-02-22 at 10:15 -0500, Doug Hellmann 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, you want to put _Python_ APIs in 'doc/source/reference/api' (you
could drop the '/api' bit too, I guess). REST API should stay in 'api-
ref' for the above reasons. Perhaps projects other than Tempest aren't
doing this consistently, in which case we should probably fix that, but
REST APIs should stay where they are, I think.

Stephen

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