Prefix sphinx section labels with document name to avoid clashes

Otherwise we have clashes if we have the same sections in different
documents (ex: "Role variables").

Change-Id: I299f982fce26bdc66caca83f845f8b44ab9e63af

doc/source/ansible-role-ara-api.rst

@@ -1,2 +1,4 @@
+.. _ansible-role-ara-api:
+
 .. include:: ../../roles/ara_api/README.rst
-  :end-before: include_delimiter_end
+  :end-before: include_delimiter_end

doc/source/api-configuration.rst

@@ -178,7 +178,7 @@ API endpoints exposed by the server.
 There is no concept of granularity: users either have access to query
 everything or they don't.
 
-Enabling this feature first requires setting up :ref:`users <user management>`.
+Enabling this feature first requires setting up :ref:`users <api-security:user management>`.
 
 ARA_WRITE_LOGIN_REQUIRED
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -195,7 +195,7 @@ all API endpoints exposed by the server.
 There is no concept of granularity: users either have access to query
 everything or they don't.
 
-Enabling this feature first requires setting up :ref:`users <user management>`.
+Enabling this feature first requires setting up :ref:`users <api-security:user management>`.
 
 ARA_LOG_LEVEL
 ~~~~~~~~~~~~~

doc/source/api-security.rst

@@ -1,4 +1,4 @@
-.. security:
+.. _security:
 
 ARA API Server authentication and security
 ==========================================
@@ -19,8 +19,10 @@ deployments.
 Setting a custom secret key
 ---------------------------
 
-By default, the API server randomly generates a token for the :ref:`ARA_SECRET_KEY`
-setting if none have been supplied by the user.
+By default, the API server randomly generates a token for the
+:ref:`api-configuration:ARA_SECRET_KEY` setting if none have
+been supplied by the user.
+
 This value is persisted in the server configuration file in order to prevent
 the key from changing on every instanciation of the server.
 
@@ -86,16 +88,16 @@ for read (ex: GET) and write (ex: DELETE, POST, PATCH) requests.
 
 This is done with the two following configuration options:
 
-- :ref:`ARA_READ_LOGIN_REQUIRED` for read access
-- :ref:`ARA_WRITE_LOGIN_REQUIRED` for write access
+- :ref:`api-configuration:ARA_READ_LOGIN_REQUIRED` for read access
+- :ref:`api-configuration:ARA_WRITE_LOGIN_REQUIRED` for write access
 
 These settings are global and are effective for all API endpoints.
 
 Managing hosts allowed to serve the API
 ---------------------------------------
 
-By default, :ref:`ARA_ALLOWED_HOSTS` authorizes ``localhost``, ``::1`` and
-``127.0.0.1`` to serve requests for the API server.
+By default, :ref:`api-configuration:ARA_ALLOWED_HOSTS` authorizes
+``localhost``, ``::1`` and ``127.0.0.1`` to serve requests for the API server.
 
 In order to host an instance of the API server on another domain, the domain must
 be part of this list or the application server will deny any requests sent to
@@ -104,9 +106,9 @@ it.
 Managing CORS (cross-origin resource sharing)
 ---------------------------------------------
 
-The :ref:`ARA_CORS_ORIGIN_WHITELIST` default is designed to allow a local development
-instance of an `ara-web <https://github.com/openstack/ara-web>`_ dashboard to
-communicate with a local development instance of the API server.
+The :ref:`api-configuration:ARA_CORS_ORIGIN_WHITELIST` default is designed to
+allow a local development instance of an `ara-web <https://github.com/openstack/ara-web>`_
+dashboard to communicate with a local development instance of the API server.
 
 The whitelist must contain the domain names where you plan on hosting instances
 of ara-web.

doc/source/conf.py

@@ -33,6 +33,7 @@ extensions = [
     'sphinx.ext.autosectionlabel',
     'pygments_lexer'
 ]
+autosectionlabel_prefix_document = True
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.