Move specs under doc/source so they build

Specs were previously under doc/specs and where thus not being rendered
via the docs build process [1].  This patch moves the directory to
doc/source/specs so that'll happen now, and makes minor tweaks to the
documents themselves to clear build errors.

More work should be done at some point soon to split out the appropriate
parts of test-requirements.txt into a doc/requirements.txt.

[1] https://governance.openstack.org/tc/reference/project-testing-interface.html#documentation

Change-Id: I1e2eff09114ef2f2fca883adb454536fb39ab64d

doc/source/index.rst

@@ -41,7 +41,7 @@ Developer Documentation
 
    contributor/contributing
    contributor/devstack_setup
-
+   specs/index
 
 Indices and tables
 ==================

doc/source/specs/index.rst

@@ -0,0 +1,40 @@
+Cyborg Specs
+============
+
+Template
+--------
+.. toctree::
+   :maxdepth: 1
+
+   template
+
+Rocky
+-----
+This section has a list of specs for the Rocky release.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   rocky/approved/*
+
+Queens
+------
+This section has a list of specs for the Queens release.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   queens/approved/*
+
+Pike
+----
+This section has a list of specs for the Pike release.
+
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   pike/approved/*

doc/source/specs/queens/approved/cyborg-internal-api.rst

@@ -71,7 +71,7 @@ Driver 'POST /discovery'
 
 Trigger the discovery and setup process for a specific driver
 
-.. code_block:: init
+.. code-block:: ini
 
     Content-Type: application/json
 
@@ -87,7 +87,7 @@ ready to use entires available by the public API. Hardware are
 physical devices on nodes that may or may not be ready to use or
 even fully supported.
 
-.. code_block:: init
+.. code-block:: ini
 
     200 OK
     Content-Type: application/json
@@ -129,7 +129,7 @@ Driver 'POST /hello'
 Registers that a driver has been installed on the machine and is ready to use.
 As well as it's endpoint and hardware support.
 
-.. code_block:: init
+.. code-block:: ini
 
     Content-Type: application/json
 
@@ -160,7 +160,7 @@ Conductor 'POST /hello'
 
 Registers that an Agent has been installed on the machine and is ready to use.
 
-.. code_block:: init
+.. code-block:: ini
 
     Content-Type: application/json
 

doc/specs/index.rst

@@ -1,15 +0,0 @@
-Cyborg Specs
-============
-
-Pike
-----
-
-This section has a list of specs for Pike release.
-
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   specs/pike/approved/*
-   specs/queens/approved/*

tox.ini

@@ -57,7 +57,7 @@ ignore-path = .venv,.git,.tox,*cyborg/locale*,*lib/python*,*cyborg.egg*,api-ref/
 [testenv:docs]
 basepython = python3
 commands =
-    python setup.py build_sphinx
+    sphinx-build -b html doc/source doc/build/html
     oslo-config-generator --config-file=tools/config/cyborg-config-generator.conf
 
 [testenv:releasenotes]