yahoo-eng-team team mailing list archive

[Christian Rohmann <1946771@xxxxxxxxxxxxxxxxxx>]

Public bug reported:


This bug tracker is for errors with the documentation, use the following
as a template and remove or add fields as you see fit. Convert [ ] into
[x] to check boxes:

- [ ] This doc is inaccurate in this way: ______
- [x] This is a doc addition request.
- [ ] I have a fix to the document that I can paste below including example: input and output. 


The documentation on API Microversions (https://docs.openstack.org/nova/latest/contributor/microversions.html#other-necessary-changes) lacks a hint that the contributor must create the subfolder with the new microversion in doc/api-samples/*/$NEW_MICROVERSION in order for the samples to be rendered as JSON files by `tox -e api-samples`.

i.e when adding a new microversion `v2.91` for servers I would need to
create `doc/api-samples/servers/v2.91?`.


Apart from this documentation hint one might argue that the tox env could check for this consistency and give the contributor a proper and helpful error.


-----------------------------------
Release: 24.1.0.dev28 on 2020-04-10 11:42:50
SHA: 0a8f3e954485d2a6d80b80da50745cb7b0dbd048
Source: https://opendev.org/openstack/nova/src/doc/source/contributor/microversions.rst
URL: https://docs.openstack.org/nova/latest/contributor/microversions.html

** Affects: nova
     Importance: Undecided
         Status: New


** Tags: doc

-- 
You received this bug notification because you are a member of Yahoo!
Engineering Team, which is subscribed to OpenStack Compute (nova).
https://bugs.launchpad.net/bugs/1946771

Title:
  Doc on microversions lacks hint on creating folder in api-samples

Status in OpenStack Compute (nova):
  New

Bug description:

  This bug tracker is for errors with the documentation, use the
  following as a template and remove or add fields as you see fit.
  Convert [ ] into [x] to check boxes:

  - [ ] This doc is inaccurate in this way: ______
  - [x] This is a doc addition request.
  - [ ] I have a fix to the document that I can paste below including example: input and output. 

  
  The documentation on API Microversions (https://docs.openstack.org/nova/latest/contributor/microversions.html#other-necessary-changes) lacks a hint that the contributor must create the subfolder with the new microversion in doc/api-samples/*/$NEW_MICROVERSION in order for the samples to be rendered as JSON files by `tox -e api-samples`.

  i.e when adding a new microversion `v2.91` for servers I would need to
  create `doc/api-samples/servers/v2.91?`.

  
  Apart from this documentation hint one might argue that the tox env could check for this consistency and give the contributor a proper and helpful error.

  
  -----------------------------------
  Release: 24.1.0.dev28 on 2020-04-10 11:42:50
  SHA: 0a8f3e954485d2a6d80b80da50745cb7b0dbd048
  Source: https://opendev.org/openstack/nova/src/doc/source/contributor/microversions.rst
  URL: https://docs.openstack.org/nova/latest/contributor/microversions.html

To manage notifications about this bug go to:
https://bugs.launchpad.net/nova/+bug/1946771/+subscriptions