[docs] Implementation of the api-ref consolidation under doc/source/

Doug Hellmann doug at doughellmann.com
Thu Feb 21 18:45:53 UTC 2019


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?
-- 
Doug



More information about the openstack-discuss mailing list