os-api-ref: duplicate labels for selectors

Bug #1583623 reported by Brian Rosmaita on 2016-05-19
8
This bug affects 1 person
Affects Status Importance Assigned to Milestone
openstack-doc-tools
Low
Unassigned

Bug Description

I'm working in a tree with v1 and v2 directories in the api-ref/source directory. Each of the v1 and v2 APIs have operations to Create X, List X, Update X. I'm getting these warnings which cause the sphinx build to fail in -W mode:

api-ref/source/v2/images-images-v2.inc:88: WARNING: duplicate label create-image-selector, other instance in /home/brianr/working/git/openstack/glance/api-ref/source/v1/index.rst
api-ref/source/v2/images-images-v2.inc:508: WARNING: duplicate label delete-image-selector, other instance in /home/brianr/working/git/openstack/glance/api-ref/source/v1/index.rst
api-ref/source/v2/images-images-v2.inc:231: WARNING: duplicate label list-images-selector, other instance in /home/brianr/working/git/openstack/glance/api-ref/source/v1/index.rst
api-ref/source/v2/images-images-v2.inc:338: WARNING: duplicate label update-image-selector, other instance in /home/brianr/working/git/openstack/glance/api-ref/source/v1/index.rst

As a workaround, I changed the section titles slightly so that the generated label would be different, e.g., "List images" vs. "Show images", "Delete image" vs. "Delete an image", but we should probably look for something more robust here. Maybe a way to specify a prefix to be used for label creation within a particular file? Something like:

.. api_ref_label_prefix :: v1

Mark T. Voelker (mvoelker) wrote :

FWIW, I'm running into this while working on the Cinder v3 API ref too.

Steve Martinelli (stevemar) wrote :

Also hitting this with identity APIs (v2 and v3)

Karen Bradshaw (kbhawkey) wrote :

Is the general idea to tag a method with a version in the .rst, i.e.
version: v1 (similar to the microversion tags), or parse the method url that contains the version.
The method section header should use this version prefix or suffix (v1-Create Image).
The doc tool would strip the version prefix/suffix off the method description/label before
writing out the html. This assumes that the rst parser/html builder will be happy with the
section title changes.

Changed in openstack-doc-tools:
assignee: nobody → Karen Bradshaw (kbhawkey)
Anne Gentle (annegentle) on 2016-11-08
Changed in openstack-doc-tools:
status: New → Confirmed
importance: Undecided → Low
Changed in openstack-doc-tools:
status: Confirmed → In Progress
Changed in openstack-doc-tools:
assignee: Karen Bradshaw (kbhawkey) → nobody
status: In Progress → Confirmed
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers