openstackdocstheme

os-api-ref: duplicate labels for selectors

Bug #1583623 reported by Brian Rosmaita
8
This bug affects 1 person
Affects Status Importance Assigned to Milestone
openstackdocstheme
Confirmed
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

Tags: os-api-ref
Revision history for this message
Mark T. Voelker (mvoelker) wrote :

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

Revision history for this message
Steve Martinelli (stevemar) wrote :

Also hitting this with identity APIs (v2 and v3)

Revision history for this message
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.

Karen Bradshaw (kbhawkey)
Changed in openstack-doc-tools:
assignee: nobody → Karen Bradshaw (kbhawkey)
Anne Gentle (annegentle)
Changed in openstack-doc-tools:
status: New → Confirmed
importance: Undecided → Low
Karen Bradshaw (kbhawkey)
Changed in openstack-doc-tools:
status: Confirmed → In Progress
Karen Bradshaw (kbhawkey)
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  
Everyone can see this information.
Subscribing...

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.