Open Stack

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/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
>>>>    >
>>>>
>>>>
>>>>
>>


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20190304/4f96f2c2/attachment-0001.sig>