os-api-ref: duplicate labels for selectors

[Brian Rosmaita]

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)]

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

[Steve Martinelli (stevemar)]

Also hitting this with identity APIs (v2 and v3)

[Karen Bradshaw (kbhawkey)]

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.