work around doc build error

This patch addresses a documentation build issue caused by the
oslo.config sphinx integration. In order to unblock this repo, we can
work around the issue here while fixing it in oslo.config, then revert
this change.

Change-Id: Ie4a29e8e8d44d00354ea0dd8420bac5b8812a717
Related-Bug: #1549106
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

.gitignore

@@ -50,3 +50,4 @@ ChangeLog
 # Editors
 *~
 .*.swp
+/doc/source/sample.config

doc/source/conf.py

@@ -25,9 +25,17 @@ extensions = [
     #'sphinx.ext.intersphinx',
     'oslosphinx',
     'oslo_config.sphinxext',
+    'oslo_config.sphinxconfiggen',
     'stevedore.sphinxext',
 ]
 
+# NOTE(dhellmann): An issue with the oslo.config sphinx integration
+#                  makes the show-options directive here result in
+#                  duplicate target nodes being introduced. Until we
+#                  can fix that, use the other directive to dump a
+#                  config file and include it as literal text.
+config_generator_config_file = 'cors_config_file.cfg'
+
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable

doc/source/cors.rst

@@ -125,7 +125,14 @@ configuration, this may be done as follows.::
 Configuration Options
 ---------------------
 
-.. show-options:: oslo.middleware.cors
+.. NOTE(dhellmann): An issue with the oslo.config sphinx integration
+                    makes the show-options directive here result in
+                    duplicate target nodes being introduced. Until we
+                    can fix that, use the other directive to dump a
+                    config file and include it as literal text.
+.. .. show-options:: oslo.middleware.cors
+
+.. literalinclude:: sample.config
 
 Module Documentation
 --------------------

doc/source/cors_config_file.cfg

@@ -0,0 +1,2 @@
+[DEFAULT]
+namespace = oslo.middleware.cors