[CloudKitty][os-api-ref][openstack-dev] v1 API docs

Mariusz Karpiarz m.karpiarz at eschercloud.ai
Wed Nov 9 17:03:03 UTC 2022


All,
CloudKitty docs for v1 APIs (https://docs.openstack.org/cloudkitty/latest/api-reference/v1/v1.html) appear to be generated from the source code instead of using `os-api-ref` (https://opendev.org/openstack/os-api-ref), like in case of v2 docs.
I want to move both v1 and v2 API docs to a separate `api-ref/source` directory in the root of the repository, where we will only be using "os_api_ref" and "openstackdocstheme" Sphinx extensions, so we need to decide what to do with v1 docs.
I started rewriting v1 docs to the format supported by `os-api-ref` but they don't quite translate well to the new format, mainly because of different ways results are presented (Python objects vs JSONs). How much do we care about proper v1 API docs and would it be worth for someone (likely me) to write them again from scratch?
There is also the option for carrying over the old extensions (they are all listed here: https://opendev.org/openstack/cloudkitty/src/branch/stable/zed/doc/source/conf.py#L42-L58) but I'm not sure all of them are still supported by the system building https://docs.openstack.org/api/ and this is a good opportunity to clean this list up. :)
Please let me know if you have any ideas.
Mariusz


More information about the openstack-discuss mailing list