From 2f57bdc8ebd9cecbd75e6c568f73d8cc416c78e8 Mon Sep 17 00:00:00 2001 From: Tim Simmons Date: Wed, 8 Mar 2017 21:00:00 +0000 Subject: [PATCH] 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 | 7 +++++++ doc/ext/assets/support-matrix.js | 3 +++ doc/ext/custom_css.py | 16 +++++++++++++++ doc/ext/support_matrix.py | 28 ++++++++++++++++++++++++++- doc/source/_static/designate-docs.css | 0 doc/source/_static/support-matrix.css | 3 --- doc/source/backends/msdns_agent.rst | 8 ++++---- doc/source/conf.py | 13 +++++++++---- doc/source/rest.rst | 6 +++--- doc/source/rest/admin/quotas.rst | 6 +++--- doc/source/rest/v1/records.rst | 5 +++-- doc/source/rest/v1/servers.rst | 2 +- 12 files changed, 76 insertions(+), 21 deletions(-) create mode 100644 doc/ext/assets/support-matrix.css create mode 100644 doc/ext/assets/support-matrix.js create mode 100644 doc/ext/custom_css.py create mode 100644 doc/source/_static/designate-docs.css delete mode 100644 doc/source/_static/support-matrix.css diff --git a/doc/ext/assets/support-matrix.css b/doc/ext/assets/support-matrix.css new file mode 100644 index 000000000..bee848d24 --- /dev/null +++ b/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 +} diff --git a/doc/ext/assets/support-matrix.js b/doc/ext/assets/support-matrix.js new file mode 100644 index 000000000..9e15e1202 --- /dev/null +++ b/doc/ext/assets/support-matrix.js @@ -0,0 +1,3 @@ +(function() { + $('.docs-book-wrapper:has(#dns-server-driver-support-matrix)').addClass('wide') +})(); diff --git a/doc/ext/custom_css.py b/doc/ext/custom_css.py new file mode 100644 index 000000000..cbaffcaba --- /dev/null +++ b/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') diff --git a/doc/ext/support_matrix.py b/doc/ext/support_matrix.py index 1bbb09da4..6c3d0fe3a 100644 --- a/doc/ext/support_matrix.py +++ b/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) diff --git a/doc/source/_static/designate-docs.css b/doc/source/_static/designate-docs.css new file mode 100644 index 000000000..e69de29bb diff --git a/doc/source/_static/support-matrix.css b/doc/source/_static/support-matrix.css deleted file mode 100644 index c41905312..000000000 --- a/doc/source/_static/support-matrix.css +++ /dev/null @@ -1,3 +0,0 @@ -.docs-body .section h1 { - display: block; -} diff --git a/doc/source/backends/msdns_agent.rst b/doc/source/backends/msdns_agent.rst index 3f2976e6b..e112a1d7b 100644 --- a/doc/source/backends/msdns_agent.rst +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 934cc1df2..4d8652389 100644 --- a/doc/source/conf.py +++ b/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 = [] diff --git a/doc/source/rest.rst b/doc/source/rest.rst index b0369b72f..14691da31 100644 --- a/doc/source/rest.rst +++ b/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 - Accept: application/json # Headers + POST /v2/pools HTTP/1.1 + Accept: application/json Content-Type: application/json - { # The rest is the body of request + { "name": "Example Pool", "ns_records": [ { diff --git a/doc/source/rest/admin/quotas.rst b/doc/source/rest/admin/quotas.rst index 6c87d7869..1c4cdf00f 100644 --- a/doc/source/rest/admin/quotas.rst +++ b/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 diff --git a/doc/source/rest/v1/records.rst b/doc/source/rest/v1/records.rst index 6cf9fdc1d..c4077c751 100644 --- a/doc/source/rest/v1/records.rst +++ b/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 diff --git a/doc/source/rest/v1/servers.rst b/doc/source/rest/v1/servers.rst index 64446ddc2..90e218233 100644 --- a/doc/source/rest/v1/servers.rst +++ b/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