docs: Move configuration reference to subpath

This allows us to add configuration scenarios.

Change-Id: Id636f78c61237fb27fa65fa3d4b3fc1a4cf0ba6a
Story: 2004360
Task: 40777

doc/requirements.txt

@@ -6,3 +6,4 @@ openstackdocstheme>=2.2.1 # Apache-2.0
 reno>=3.1.0 # Apache-2.0
 sphinx>=2.0.0,!=2.1.0 # BSD
 sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
+whereto>=0.3.0 # Apache-2.0

doc/source/_extra/.htaccess

@@ -0,0 +1,14 @@
+# The following redirects were added when configuration/* was moved to
+# configuration/reference/*.
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/ansible.html$	/$1/configuration/reference/ansible.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/bifrost.html$	/$1/configuration/reference/bifrost.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/docker-registry.html$	/$1/configuration/reference/docker-registry.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/hosts.html$	/$1/configuration/reference/hosts.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/ironic-python-agent.html$	/$1/configuration/reference/ironic-python-agent.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/kayobe.html$	/$1/configuration/reference/kayobe.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/kolla-ansible.html$	/$1/configuration/reference/kolla-ansible.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/kolla.html$	/$1/configuration/reference/kolla.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/network.html$	/$1/configuration/reference/network.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/nova-cells.html$	/$1/configuration/reference/nova-cells.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/physical-network.html$	/$1/configuration/reference/physical-network.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/seed-custom-containers.html$	/$1/configuration/reference/seed-custom-containers.html

doc/source/conf.py

@@ -69,6 +69,10 @@ pygments_style = 'native'
 html_theme = 'openstackdocs'
 # html_static_path = ['static']
 
+# Add any paths that contain "extra" files, such as .htaccess or
+# robots.txt.
+html_extra_path = ['_extra']
+
 html_theme_options = {
     "show_other_versions": True,
 }

doc/source/configuration/index.rst

@@ -5,15 +5,4 @@ Configuration Guide
 .. toctree::
    :maxdepth: 2
 
-   kayobe
+   reference/index
-   ansible
-   physical-network
-   network
-   hosts
-   kolla
-   kolla-ansible
-   bifrost
-   ironic-python-agent
-   docker-registry
-   seed-custom-containers
-   nova-cells

doc/source/configuration/reference/index.rst

@@ -0,0 +1,22 @@
+=======================
+Configuration Reference
+=======================
+
+This section provides detailed information on many of Kayobe's configuration
+options.
+
+.. toctree::
+   :maxdepth: 2
+
+   kayobe
+   ansible
+   physical-network
+   network
+   hosts
+   kolla
+   kolla-ansible
+   bifrost
+   ironic-python-agent
+   docker-registry
+   seed-custom-containers
+   nova-cells

doc/source/configuration/reference/seed-custom-containers.rst

@@ -56,6 +56,6 @@ module page.
 
 List of Kayobe applied defaults to required docker_container variables:
 
-.. literalinclude:: ../../../ansible/roles/deploy-containers/defaults/main.yml
+.. literalinclude:: ../../../../ansible/roles/deploy-containers/defaults/main.yml
     :language: yaml
 

doc/test/redirect-tests.txt

@@ -0,0 +1,25 @@
+# This file contains tests for redirects to handle existing URLs for
+# specs that have been moved. See
+# https://docs.openstack.org/whereto/latest/ for details.
+
+# No redirect.
+/ 200
+/kayobe 200
+/kayobe/latest 200
+/kayobe/latest/configuration/ 200
+/kayobe/latest/configuration/index.html 200
+/kayobe/latest/configuration/reference/index.html 200
+
+# Moved /kayobe/latest/configuration/*.html to /kayobe/latest/configuration/reference/
+/kayobe/latest/configuration/ansible.html 301 /kayobe/latest/configuration/reference/ansible.html
+/kayobe/latest/configuration/bifrost.html 301 /kayobe/latest/configuration/reference/bifrost.html
+/kayobe/latest/configuration/docker-registry.html 301 /kayobe/latest/configuration/reference/docker-registry.html
+/kayobe/latest/configuration/hosts.html 301 /kayobe/latest/configuration/reference/hosts.html
+/kayobe/latest/configuration/ironic-python-agent.html 301 /kayobe/latest/configuration/reference/ironic-python-agent.html
+/kayobe/latest/configuration/kayobe.html 301 /kayobe/latest/configuration/reference/kayobe.html
+/kayobe/latest/configuration/kolla-ansible.html 301 /kayobe/latest/configuration/reference/kolla-ansible.html
+/kayobe/latest/configuration/kolla.html 301 /kayobe/latest/configuration/reference/kolla.html
+/kayobe/latest/configuration/network.html 301 /kayobe/latest/configuration/reference/network.html
+/kayobe/latest/configuration/nova-cells.html 301 /kayobe/latest/configuration/reference/nova-cells.html
+/kayobe/latest/configuration/physical-network.html 301 /kayobe/latest/configuration/reference/physical-network.html
+/kayobe/latest/configuration/seed-custom-containers.html 301 /kayobe/latest/configuration/reference/seed-custom-containers.html

tox.ini

@@ -115,6 +115,7 @@ deps =
 commands =
   rm -rf doc/build/html
   sphinx-build -W --keep-going -b html doc/source doc/build/html
+  whereto doc/source/_extra/.htaccess doc/test/redirect-tests.txt
 
 [testenv:pdf-docs]
 whitelist_externals = make