[docs] Implementation of the api-ref consolidation under doc/source/
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]. (most likely anything below applies to releasenotes/ as well.) I asked about this item few weeks ago on the documentation channels. So far no one seems against moving forward with this, but, you know, resources :) I think that the process itself shouldn't be too complicated on the technical side, but more on the definition of the desired outcome. I can help with the technical part (the moving), but it would be better if someone from the doc team with the required knowledge and background on the doc process would start with at least a draft of a spec, which can be used to start the discussion. If implemented, this change would also fix an inconsistency in the guidelines [2]: the content of reference/ seems to overlap with the content of api- ref("Library projects should place their automatically generated class documentation here."), but then having api-ref there would allow us to always use api-ref. That's where the entire discussion started in the QA session [3]: some client libraries document their API in different places. [1] https://etherpad.openstack.org/p/docs-i18n-ptg-stein line 144 [2] https://docs.openstack.org/doc-contrib-guide/project-guides.html [3] https://etherpad.openstack.org/p/clean-up-the-tempest-documentation Ciao -- Luigi
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?
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? Ciao -- Luigi
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? -- Doug
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. [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
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.
[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
On Fri, 2019-02-22 at 10:15 -0500, Doug Hellmann 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, 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-migra...
Ciao -- Luigi
---- 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
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@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
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. 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/) Thanks, Graham 1 - https://github.com/openstack/openstackdocstheme/blob/master/openstackdocsthe... 2 - https://github.com/openstack/openstackdocstheme/blob/master/api-ref/source/c...
On 22/02/2019 22:46, Ghanshyam Mann wrote:
---- 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
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/openstackdocsthe...
2 - https://github.com/openstack/openstackdocstheme/blob/master/api-ref/source/c...
On 22/02/2019 22:46, Ghanshyam Mann wrote:
---- 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
On 04/03/2019 16:48, Alexandra Settle wrote:
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
I think (looking at the list of projects that have content in the api-ref folder) [1] all of the projects I checked seem to be OK. The only oddities are the stx-* repos, and that is outside of our scope. (As a side note, we really do need to update the dropdown on the api-ref sub-theme.) 1 : ➜ ~ http GET http://codesearch.openstack.org/api/v1/search files=="^api-ref/source/index.rst" q==".*" repos=='*' | jq '.Results | keys' [ "adjutant", "barbican", "blazar", "cinder", "designate", "distil", "ec2-api", "freezer-api", "glance", "heat", "ironic", "ironic-inspector", "karbor", "keystone", "magnum", "manila", "masakari", "mistral", "mogan", "monasca-api", "monasca-events-api", "monasca-log-api", "murano", "networking-sfc", "neutron-lib", "nova", "octavia", "openstackdocstheme", "placement", "sahara", "searchlight", "senlin", "stx-config", "stx-distcloud", "stx-docs", "stx-fault", "stx-ha", "stx-metal", "stx-nfv", "stx-update", "swift", "tacker", "trove", "valence", "valet", "watcher", "zaqar", "zun" ]
Thanks,
Graham
1 - https://github.com/openstack/openstackdocstheme/blob/master/openstackdocsthe...
2 - https://github.com/openstack/openstackdocstheme/blob/master/api-ref/source/c...
On 22/02/2019 22:46, Ghanshyam Mann wrote:
---- 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
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?
As Doug pointed out, it is very difficult to split out a generated set of documentation from Sphinx. There are too many links between the resulting output. Assuming that is possible, the existing standard set of jobs for publishing these to their respective locations cannot handle this. It would be a non-standard thing (unless all repos switched over to this new structure) so it would not be able to run the jobs that are expected of all projects. We would also need to update the published documentation for how this should be done here: https://governance.openstack.org/tc/reference/project-testing-interface.html... If the desire is to better organize documentation files within the repo, I could see potentially having being able to more easily do something where you have doc/source, doc/api-ref, and doc/releasenotes. But the few things mentioned above would need to be updated to allow that.
If we move the api-ref into doc/source, we should follow the example done by install-guides move: Publish as a single tree to docs.openstack.org and stop publishing to developer.openstack.org. If we want to keep publishing to developer.o.o, let's not move - it gets too complicated, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
On Thu, 2019-02-21 at 18:08 +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].
(most likely anything below applies to releasenotes/ as well.)
I asked about this item few weeks ago on the documentation channels. So far no one seems against moving forward with this, but, you know, resources :)
I think that the process itself shouldn't be too complicated on the technical side, but more on the definition of the desired outcome. I can help with the technical part (the moving), but it would be better if someone from the doc team with the required knowledge and background on the doc process would start with at least a draft of a spec, which can be used to start the discussion.
If implemented, this change would also fix an inconsistency in the guidelines [2]: the content of reference/ seems to overlap with the content of api- ref("Library projects should place their automatically generated class documentation here."), but then having api-ref there would allow us to always use api-ref. That's where the entire discussion started in the QA session [3]: some client libraries document their API in different places.
I thought the reason we hadn't done this was because the API reference was intentionally unversioned, while the of the documentation was not? What's changed that we could start moving this in-tree? Stephen
[1] https://etherpad.openstack.org/p/docs-i18n-ptg-stein line 144 [2] https://docs.openstack.org/doc-contrib-guide/project-guides.html [3] https://etherpad.openstack.org/p/clean-up-the-tempest-documentation
Ciao
On 22/02/2019 10:47, Stephen Finucane wrote:
On Thu, 2019-02-21 at 18:08 +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].
(most likely anything below applies to releasenotes/ as well.)
I asked about this item few weeks ago on the documentation channels. So far no one seems against moving forward with this, but, you know, resources :)
I think that the process itself shouldn't be too complicated on the technical side, but more on the definition of the desired outcome. I can help with the technical part (the moving), but it would be better if someone from the doc team with the required knowledge and background on the doc process would start with at least a draft of a spec, which can be used to start the discussion.
If implemented, this change would also fix an inconsistency in the guidelines [2]: the content of reference/ seems to overlap with the content of api- ref("Library projects should place their automatically generated class documentation here."), but then having api-ref there would allow us to always use api-ref. That's where the entire discussion started in the QA session [3]: some client libraries document their API in different places. I thought the reason we hadn't done this was because the API reference was intentionally unversioned, while the of the documentation was not? What's changed that we could start moving this in-tree?
Now you say it out loud, I'm fairly certain this is exactly why we didn't do it. As per the spec we wrote for the OS manuals migration, we did "say" we were going to do this work. See [4]. Although the caveat was "... is deferred until we are farther (further, jeez) along with the initial migration work." I'm not sure if we have any other historical notes on this. [4] https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migra...
Stephen
[1] https://etherpad.openstack.org/p/docs-i18n-ptg-stein line 144 [2] https://docs.openstack.org/doc-contrib-guide/project-guides.html [3] https://etherpad.openstack.org/p/clean-up-the-tempest-documentation
Ciao
participants (8)
-
Alexandra Settle
-
Andreas Jaeger
-
Doug Hellmann
-
Ghanshyam Mann
-
Graham Hayes
-
Luigi Toscano
-
Sean McGinnis
-
Stephen Finucane