---- On Sat, 23 Feb 2019 00:14:41 +0900 Doug Hellmann <doug@doughellmann.com> wrote ----
Luigi Toscano <ltoscano@redhat.com> writes:
On Thursday, 21 February 2019 19:45:53 CET Doug Hellmann wrote:
Luigi Toscano <ltoscano@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-migra...
Ciao -- Luigi
-- Doug