Open Stack

On 04/03/2019 14:29, Graham Hayes wrote:
> On 04/03/2019 14:13, Alexandra Settle wrote:
>> 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.
> Personally, I don't think moving api-ref is worth the effort.
Seems to be the general consensus.
>
> There is a lot of tools that assume the location[1][2], and building it
> as one tree would require a lot of work.
>
> We should differentiate between python API documentation (should be
> in doc/source) and HTTP API documentation (in api-ref/)

How many repos would we need to do this for?

Cheers,

Alex

>
> Thanks,
>
> Graham
>
> 1 -
> https://github.com/openstack/openstackdocstheme/blob/master/openstackdocstheme/theme/openstackdocs/sidebartoc_menu_apiref.html
>
> 2 -
> https://github.com/openstack/openstackdocstheme/blob/master/api-ref/source/conf.py#L123-L126
>
>> 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
>>>    >
>>>
>>>
>>>
>