Switch to the OpenStack Docs Theme

Updated the theme, added some custom css for the
backends matrix, and moved the toc to the sidebar

Change-Id: Ibb7860d9ddc16e5d81e127c8713c810122c2c25f

doc/ext/assets/support-matrix.css

@@ -0,0 +1,7 @@
+.docs-body #dns-server-driver-support-matrix h1 {
+    display: block;
+}
+
+.docs-book-wrapper.wide {
+  width: 90% !important
+}

doc/ext/assets/support-matrix.js

@@ -0,0 +1,3 @@
+(function() {
+    $('.docs-book-wrapper:has(#dns-server-driver-support-matrix)').addClass('wide')
+})();

doc/ext/custom_css.py

@@ -0,0 +1,16 @@
+# Copyright (C) 2014 Red Hat, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+def setup(app):
+    app.add_stylesheet('designate-docs.css')

doc/ext/support_matrix.py

@@ -21,6 +21,8 @@ It is used via a single directive in the .rst file
   .. support_matrix::
 
 """
+import os
+
 import six
 import six.moves.configparser as config_parser
 import sys
@@ -29,6 +31,7 @@ from docutils import nodes
 from docutils.parsers import rst
 from designate.backend.base import Backend
 from designate.backend.agent_backend.base import AgentBackend
+from sphinx.util.osutil import copyfile
 
 
 class SupportMatrix(object):
@@ -427,6 +430,29 @@ class SupportMatrixDirective(rst.Directive):
         return content
 
 
-def setup(app):
+def copy_assets(app, exception):
+    assets = ['support-matrix.css', 'support-matrix.js']
+    if app.builder.name != 'html' or exception:
+        return
+    app.info('Copying assets: %s' % ', '.join(assets))
+    for asset in assets:
+        dest = os.path.join(app.builder.outdir, '_static', asset)
+        source = os.path.abspath(os.path.dirname(__file__))
+        copyfile(os.path.join(source, 'assets', asset), dest)
+
+
+def add_assets(app):
     app.add_stylesheet('support-matrix.css')
+    app.add_javascript('support-matrix.js')
+
+
+def setup(app):
+
+    # Add all the static assets to our build during the early stage of building
+    app.connect('builder-inited', add_assets)
+
+    # This copies all the assets (css, js, fonts) over to the build
+    # _static directory during final build.
+    app.connect('build-finished', copy_assets)
+
     app.add_directive('support_matrix', SupportMatrixDirective)

doc/source/_static/support-matrix.css

@@ -1,3 +0,0 @@
-.docs-body .section h1 {
-    display: block;
-}

doc/source/backends/msdns_agent.rst

@@ -53,7 +53,7 @@ Make sure that Python 2.7 or Python 3.4 is installed on the system already.
 To install Designate, clone the repository from https://github.com/openstack/designate
 and do a pip install. Example:
 
-.. code-block:: powershell
+.. code-block:: console
 
     git clone https://github.com/openstack/designate
     pip install .\\designate
@@ -66,7 +66,7 @@ Inside the configuration folder, make a copy of designate.conf.sample and rename
 the copy to designate.conf
 Example:
 
-.. code-block:: powershell
+.. code-block:: console
 
     copy C:\\etc\\designate\\designate.conf.sample C:\\etc\\designate\\designate.conf
 
@@ -91,13 +91,13 @@ Ensure that "policy_file" under the [default] section is set:
 
 Start the designate agent using (Python 2.7 was installed in the default location C:\\Python27):
 
-.. code-block:: powershell
+.. code-block:: console
 
     C:\\Python27\\Scripts\\designate-agent.exe --config-file 'C:\\etc\\designate\\designate.conf'
 
 You should see log messages similar to:
 
-.. code-block:: powershell
+.. code-block:: console
 
     2016-06-22 02:00:47.177 3436 INFO designate.backend.agent_backend.impl_msdns [-] Started msdns backend
     2016-06-22 02:00:47.177 3436 INFO designate.service [-] _handle_tcp thread started

doc/source/conf.py

@@ -12,6 +12,7 @@
 # serve to show the default.
 
 import sys, os
+import openstackdocstheme
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -30,8 +31,8 @@ sys.path.insert(0, os.path.abspath('./'))
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.viewcode',
               'sphinxcontrib.httpdomain',
-              'oslosphinx',
+              'ext.support_matrix',
-              'ext.support_matrix']
+              'ext.custom_css']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -98,12 +99,16 @@ modindex_common_prefix = ["designate."]
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'openstackdocs'
+html_theme_path = [openstackdocstheme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {}
+html_theme_options = {
+    "sidebar_mode": "toc",
+    "display_toc": True
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

doc/source/rest.rst

@@ -12,11 +12,11 @@ example:
 
 .. code-block:: http
 
-   POST /v2/pools HTTP/1.1          # The HTTP Method, Path and HTTP Version
+   POST /v2/pools HTTP/1.1
-   Accept: application/json         # Headers
+   Accept: application/json
    Content-Type: application/json
 
-   {                                # The rest is the body of request
+   {
         "name": "Example Pool",
         "ns_records": [
             {

doc/source/rest/admin/quotas.rst

@@ -25,7 +25,7 @@ The quotas extension can be used to retrieve a tenant's absolute limits.
 
 *Note*: Quotas is an extension and needs to be enabled before it can be used.
 If Designate returns a 404 error, ensure that the following line has been
-added to the designate.conf file under "[service:api]" section ::
+added to the designate.conf file under ``[service:api]`` section ::
 
     enable_api_admin = True
     enabled_extensions_admin = quotas
@@ -53,7 +53,7 @@ Get Quotas
 
     **Example response:**
 
-    .. sourcecode:: http
+    .. sourcecode:: guess
 
         HTTP/1.1 201 Created
         Content-Type: application/json
@@ -104,7 +104,7 @@ Update Quotas
 
     **Example response:**
 
-    .. sourcecode:: http
+    .. sourcecode:: guess
 
         HTTP/1.1 200 OK
         Content-Type: application/json

doc/source/rest/v1/records.rst

@@ -674,10 +674,11 @@ Update a record
 
    .. sourcecode:: http
 
-      PUT /domains/89acac79-38e7-497d-807c-a011e1310438/records/2e32e609-3a4f-45ba-bdef-e50eacd345ad
+      PUT /domains/89acac79-38e7-497d-807c-a011e1310438/records/2e32e609-3a4f-45ba-bdef-e50eacd345ad HTTP/1.1
       Host: example.com
       Accept: application/json
       Content-Type: application/json
+
       {
         "name": "www.example.com.",
         "type": "A",
@@ -763,7 +764,7 @@ List Records in a Domain
 
    **Example response**:
 
-   .. sourcecode:: http
+   .. sourcecode:: guess
 
       Content-Type: application/json
       Content-Length: 1209

doc/source/rest/v1/servers.rst

@@ -192,7 +192,7 @@ Delete Server
 
   **Example response**
 
-  .. sourcecode:: http
+  .. sourcecode:: guess
 
       HTTP/1.1 200 OK
       Content-Type: text/html; charset=utf-8