Open Stack

This conversation went a little stale, much like the first time we 
attempted to chat about this.

Starting from the top: Is this something we need to consider for the 
next release? It sounds like we have a lot of different thoughts, and it 
might be worth scrapping from the previous releases' goals.

On 22/02/2019 22:46, Ghanshyam Mann wrote:
> ---- 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
>   >
>
>
>