API References dropdown menu

- Adds a theme variable, sidebar_dropdown, to set
  a dropdown menu for the API references.
  To test, uncomment the parameter html_theme_options in
  doc/source/conf.py OR build the API Ref demo docs.
- Adds an API Ref docs demo integrating os-api-ref
  and openstackdocstheme. Tested with webserver:
  python -m SimpleHTTPServer <port_num>.

Change-Id: I346695cd407ecf4efc0a5e00f2c0ccc1ea099ec5

.gitignore

@@ -6,6 +6,7 @@ _build/
 *.pyc
 doc/build
 doc/source/BBresult
+api-ref/build
 .tox
 
 # Editors

api-ref/source/_static/css/README.md

@@ -0,0 +1,5 @@
+<!--
+This directory is set in conf.py as html_static_path.
+See http://www.sphinx-doc.org/en/stable/config.html#confval-html_static_path
+for further details.
+-->

api-ref/source/conf.py

@@ -0,0 +1,173 @@
+# -*- coding: utf-8 -*-
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import subprocess
+import sys
+import 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
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+
+extensions = [
+    'os_api_ref',
+]
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# "project" contains the name of the book, such as
+# 'security guide' or 'network guide'
+# It's used by the "log-a-bug" button on each page
+# and should ultimately be set automatically by the build process
+project = u'Test API Reference'
+copyright = u'2016, OpenStack Contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# "version" and "release" are used by the "log-a-bug" feature
+#
+# The short X.Y version.
+version = '1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0'
+
+# A few variables have to be set for the log-a-bug feature.
+#   giturl: The location of conf.py on Git. Must be set manually.
+#   gitsha: The SHA checksum of the bug description. Automatically extracted from git log.
+#   bug_tag: Tag for categorizing the bug. Must be set manually.
+# These variables are passed to the logabug code via html_context.
+giturl = u'http://git.openstack.org/cgit/openstack/openstackdocstheme/tree/doc/source'
+git_cmd = ["/usr/bin/git", "rev-parse", "HEAD"]
+gitsha = subprocess.Popen(
+    git_cmd, stdout=subprocess.PIPE).communicate()[0].strip('\n')
+bug_tag = "doc-builds"
+
+html_context = {"gitsha": gitsha, "bug_tag": bug_tag, "giturl": giturl}
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'openstackdocs'
+
+# 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.
+
+# To use the API Reference sidebar dropdown menu,
+# uncomment the html_theme_options parameter.  The theme
+# variable, sidebar_dropdown, should be set to `api_ref`.
+# Otherwise, the list of links for the User and Ops docs
+# appear in the sidebar dropdown menu.
+html_theme_options = {"sidebar_dropdown": "api_ref",
+                      "sidebar_mode": "toc"}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = [openstackdocstheme.get_html_theme_path()]
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static/css']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# So that we can enable "log-a-bug" links from each output HTML page, this
+# variable must be set to a format that includes year, month, day, hours and
+# minutes.
+html_last_updated_fmt = '%Y-%m-%d %H:%M'

api-ref/source/index.rst

@@ -0,0 +1,9 @@
+:tocdepth: 2
+
+==================
+ Test Service API
+==================
+
+.. rest_expand_all::
+
+.. include:: service.inc

api-ref/source/parameters.yaml

@@ -0,0 +1,24 @@
+id:
+  in: path
+  required: true
+  type: string
+  description: |
+    The id of the service.
+host:
+  in: body
+  required: true
+  type: string
+  description: |
+    The host name.
+name:
+  in: body
+  required: true
+  type: string
+  description: |
+    The name of the service.
+server.obj:
+  in: body
+  required: true
+  type: object
+  description: |
+    The server object.

api-ref/source/service.inc

@@ -0,0 +1,165 @@
+.. -*- rst -*-
+
+This is a Test Service API Reference.
+
+List the Servers
+================
+
+Testing API for Service 1.
+
+**Passwords**
+
+When you create a server, you can specify a password through the
+optional adminPass attribute. The password must meet the complexity
+requirements set by your OpenStack Compute provider. The server might
+enter an ``ERROR`` state if the complexity requirements are not met. In
+this case, a client might issue a change password action to reset the
+server password.
+
+If you do not specify a password, the API generates and assigns a random
+password that it returns in the response object. This password meets the
+security requirements set by the compute provider. For security reasons,
+subsequent GET calls do not require this password.
+
+**Server metadata**
+
+You can specify custom server metadata at server launch time. The
+maximum size for each metadata key-value pair is 255 bytes. The compute
+provider determines the maximum number of key-value pairs for each
+server. You can query this value through the ``maxServerMeta`` absolute
+limit.
+
+**Server networks**
+
+You can specify one or more networks to which the server connects at
+launch time. Users can also specify a specific port on the network or
+the fixed IP address to assign to the server interface.
+
+    **Note**
+
+    You can use both IPv4 and IPv6 addresses as access addresses and you
+    can assign both addresses simultaneously. You can update access
+    addresses after you create a server.
+
+**Server personality**
+
+To customize the personality of a server instance, you can inject data
+into its file system. For example, you might insert ssh keys, set
+configuration files, or store data that you want to retrieve from inside
+the instance. This customization method provides minimal launch-time
+personalization. If you require significant customization, create a
+custom image.
+
+Follow these guidelines when you inject files:
+
+-  The maximum size of the file path data is 255 bytes.
+
+-  Encode the file contents as a Base64 string. The compute provider
+   determines the maximum size of the file contents. The image that you
+   use to create the server determines this value.
+
+   .. note::
+
+       The maximum limit refers to the number of bytes in the decoded
+       data and not to the number of characters in the encoded data.
+
+-  The ``maxPersonality`` absolute limit defines the maximum number of
+   file path and content pairs that you can supply. The compute provider
+   determines this value.
+
+-  The ``maxPersonalitySize`` absolute limit is a byte limit that
+   applies to all images in the deployment. Providers can set additional
+   per-image personality limits.
+
+The file injection might not occur until after the server builds and
+boots.
+
+After file injection, only system administrators can access personality
+files. For example, on Linux, all files have root as the owner and the
+root group as the group owner, and allow only user and group read access
+(``chmod 440``).
+
+**Server access addresses**
+
+In a hybrid environment, the underlying implementation might not control
+the IP address of a server. Instead, the access IP address might be part
+of the dedicated hardware; for example, a router/NAT device. In this
+case, you cannot use the addresses that the implementation provides to
+access the server from outside the local LAN. Instead, the API might
+assign a separate access address at creation time to provide access to
+the server. This address might not be directly bound to a network
+interface on the server and might not necessarily appear when you query
+the server addresses. However, clients should use an access address to
+access the server directly.
+
+.. rest_method:: GET /v3/servers/{role_id}/role/{another_id}/role/{some_id}
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - host: host
+   - name: name
+
+
+Copy the Server
+===============
+
+Testing display of copy API.
+
+.. rest_method:: COPY /v3/servers/{role_id}
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - host: host
+   - name: name
+
+
+Change or Update the Servers
+============================
+
+.. rest_method:: PUT /servers
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - name: name
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - server: server.obj
+   - name: name
+
+**Example List Servers:**
+
+.. literalinclude:: update-server-resp.json
+   :language: javascript
+
+
+Delete a Server
+===============
+
+Delete some server content.
+
+.. rest_method:: DELETE /servers/{id}
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: id
+
+Response
+--------
+
+No content in body of response.

api-ref/source/update-server-resp.json

@@ -0,0 +1,5 @@
+{
+    "server": {
+        "name": "server1"
+    }
+}

doc/source/conf.py

@@ -72,7 +72,8 @@ git_cmd = ["/usr/bin/git", "rev-parse", "HEAD"]
 gitsha = subprocess.Popen(
     git_cmd, stdout=subprocess.PIPE).communicate()[0].strip('\n')
 bug_tag = "doc-builds"
-html_context = {"gitsha": gitsha, "bug_tag": bug_tag, "giturl" : giturl}
+
+html_context = {"gitsha": gitsha, "bug_tag": bug_tag, "giturl": giturl}
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -122,7 +123,13 @@ html_theme = 'openstackdocs'
 # 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 = {}
+
+# To use the API Reference sidebar dropdown menu,
+# uncomment the html_theme_options parameter.  The theme
+# variable, sidebar_dropdown, should be set to `api_ref`.
+# Otherwise, the list of links for the User and Ops docs
+# appear in the sidebar dropdown menu.
+#html_theme_options = {"sidebar_dropdown": "api_ref"}
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = [openstackdocstheme.get_html_theme_path()]

openstackdocstheme/theme/openstackdocs/js.html

@@ -1,5 +1,5 @@
 {%- for jsfile in script_files %}
-{% if jsfile not in ('_static/jquery.js', '_static/underscore.js', '_static/doctools.js') %}
+{%- if jsfile not in ('_static/jquery.js', '_static/bootstrap.min.js', '_static/underscore.js', '_static/doctools.js') %}
 <script src="{{ pathto(jsfile, 1) }}" type="text/javascript"></script>
-{% endif %}
+{%- endif %}
 {%- endfor %}

openstackdocstheme/theme/openstackdocs/sidebartoc.html

@@ -4,23 +4,12 @@
   </div>
   <div class="btn-group docs-sidebar-releases">
     <button onclick="location.href='/'" class="btn docs-sidebar-home" data-toggle="tooltip" data-placement="top" title="Docs Home"><i class="fa fa-arrow-circle-o-left"></i></button>
-    <button href="#" type="button" data-toggle="dropdown" class="btn docs-sidebar-release-select">OpenStack Documentation<i class="fa fa-caret-down"></i></button>
-    <ul class="dropdown-menu docs-sidebar-dropdown" role="menu" aria-labelledby="dLabel">
-      <li role="presentation" class="dropdown-header">Guides</li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#install-guides">Install Guides</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#user-guides">User Guides</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#configuration-guides">Configuration Guides</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#ops-and-admin-guides">Operations and Administration Guides</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#api-guides">API Guides</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#contributor-guides">Contributor Guides</a></li>
-      <li role="presentation" class="dropdown-header">Languages</li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/ja/">日本語 (Japanese)</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/de/">Deutsch (German)</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/fr/">Français (French)</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/pt_BR/">Português (Portuguese)</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/zh_CN/">简体中文 (Simplified Chinese)</a></li>
-      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/ko_KR/">한국어 (Korean)</a></li>
-    </ul>
+
+{%- if theme_sidebar_dropdown == 'api_ref'%}
+{% include 'sidebartoc_menu_apiref.html' %}
+{%- else %}
+{% include 'sidebartoc_menu.html' %}
+{%- endif %}
   </div>
   <div class="docs-sidebar-toc">
     <div class="docs-sidebar-section" id="table-of-contents">

openstackdocstheme/theme/openstackdocs/sidebartoc_menu.html

@@ -0,0 +1,17 @@
+<button href="#" type="button" data-toggle="dropdown" class="btn docs-sidebar-release-select">OpenStack Documentation<i class="fa fa-caret-down"></i></button>
+    <ul class="dropdown-menu docs-sidebar-dropdown" role="menu" aria-labelledby="dLabel">
+      <li role="presentation" class="dropdown-header">Guides</li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#install-guides">Install Guides</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#user-guides">User Guides</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#configuration-guides">Configuration Guides</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#ops-and-admin-guides">Operations and Administration Guides</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#api-guides">API Guides</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/index.html#contributor-guides">Contributor Guides</a></li>
+      <li role="presentation" class="dropdown-header">Languages</li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/ja/">日本語 (Japanese)</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/de/">Deutsch (German)</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/fr/">Français (French)</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/pt_BR/">Português (Portuguese)</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/zh_CN/">简体中文 (Simplified Chinese)</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://docs.openstack.org/ko_KR/">한국어 (Korean)</a></li>
+    </ul>

openstackdocstheme/theme/openstackdocs/sidebartoc_menu_apiref.html

@@ -0,0 +1,19 @@
+<button href="#" type="button" data-toggle="dropdown" class="btn docs-sidebar-release-select">OpenStack APIs<i class="fa fa-caret-down"></i></button>
+    <ul class="dropdown-menu docs-sidebar-dropdown" role="menu" aria-labelledby="dLabel">
+      <li role="presentation" class="dropdown-header">References</li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/baremetal/index.html">Bare Metal</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/clustering/index.html">Clustering</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/compute/index.html">Compute</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/data-processing/index.html">Data Processing</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/dns/index.html">DNS</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/identity/index.html">Identity</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/image/index.html">Image</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/messaging/index.html">Messaging Service</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/networking/index.html">Networking</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/object-storage/index.html">Object Storage</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/orchestration/index.html">Orchestration</a></li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-ref/shared-file-systems/index.html">Shared File Systems</a></li>
+      <li role="presentation" class="dropdown-header">Guides</li>
+      <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-guide/quick-start/">API Quick Start</a></li>
+     <li role="presentation"><a role="menuitem" tabindex="-1" href="http://developer.openstack.org/api-guide/compute/">Compute API Guide</a></li>
+    </ul>

openstackdocstheme/theme/openstackdocs/theme.conf

@@ -7,3 +7,4 @@ pygments_style = native
 analytics_tracking_code = UA-17511903-1
 sidebar_mode = toctree
 display_toc = True
+sidebar_dropdown = os_docs

releasenotes/notes/sidebar_dropdown_apiref-993b4dba4c0369f6.yaml

@@ -0,0 +1,29 @@
+---
+prelude: >
+    Adds a theme variable, ``sidebar_dropdown`` to configure
+    the display of the new API sidebar dropdown menu.
+features:
+  - |
+    Adds the option to configure the display of a sidebar dropdown
+    menu for published API References and Guides.
+    In conf.py, set the theme variable, ``html_theme_options`` to
+    include the parameter, ``sidebar_dropdown`` as ``api_ref``. For
+    example:
+
+    ::
+
+      html_theme_options = {
+           "sidebar_dropdown": "api_ref",
+        }
+
+    The extensions parameter should include the sphinx extension,
+    ``os_api_ref``.
+
+    ::
+
+      extensions = [
+          'os_api_ref',
+      ]
+
+  - Publishes an API Reference demo which is integrated with the
+    API sidebar dropdown menu.

test-requirements.txt

@@ -8,4 +8,6 @@ hacking<0.11,>=0.10.0
 sphinx!=1.3b1,<1.3,>=1.2.1 # BSD
 
 reno>=1.8.0 # Apache2
+
+os-api-ref>=0.4.0 # Apache-2.0
 oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0

tox.ini

@@ -8,6 +8,7 @@ install_command = pip install -U {opts} {packages}
 deps = -r{toxinidir}/test-requirements.txt
 setenv = VIRTUAL_ENV={envdir}
 sitepackages = False
+whitelist_externals = rm
 
 [testenv:pep8]
 commands =
@@ -17,10 +18,20 @@ commands =
 commands = {posargs}
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands =
+  rm -rf doc/build api-ref/build
+  python setup.py build_sphinx
+  sphinx-build -a -E -W -d api-ref/build/doctrees -b html api-ref/source api-ref/build/html
 
 [testenv:releasenotes]
-commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+commands =
+  rm -rf releasenotes/build
+  sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+
+[testenv:api-ref]
+commands =
+  rm -rf api-ref/build
+  sphinx-build -a -E -W -d api-ref/build/doctrees -b html api-ref/source api-ref/build/html
 
 [flake8]
 exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,tools