Publishing API Guide to OpenStack site

Moving files from doc/source/api/userguide/*.rst
to api-guide/source/*.rst,
also add api-guide/source/conf.py for building api-guide,
add a new tox target named api-guide
Taking a reference from this patch which was used for the
similar migration of Nova api guide:
https://review.openstack.org/#/c/230186

Change-Id: I725e7939f9a88185de6ef32b311159b0924b7183
Partial-Bug: #1540665
Needed-By: I7b7c623e6299c803930e41d72510f1a67d909fa3

api-guide/source/acls.rst

@@ -11,7 +11,8 @@ such as at the user level. The Access Control List (ACL) feature supports this m
 access.
 
 This guide will assume you will be using a local running development environment of barbican.
-If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
+If you need assistance with getting set up, please reference the
+`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__
 
 .. warning::
 
@@ -69,7 +70,7 @@ to `project-access` as true and no `users` in ACL settings. That's why every sec
 default has following implicit ACL.
 
 .. code-block:: json
-    
+
     {
       "read":{
         "project-access": true
@@ -143,8 +144,10 @@ To set/replace an ACL for a container:
     HTTP/1.1 201 Created
     {"acl_ref": "http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl"}
 
-To get more details on the create API you can reference the :ref:`Set Secret ACL <put_secret_acl>`
-or :ref:`Set Container ACL <put_container_acl>` documentation.
+To get more details on the create API you can reference the
+`Set Secret ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#put-v1-secrets-uuid-acl>`__
+or `Set Container ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#put-v1-containers-uuid-acl>`__
+documentation.
 
 
 .. _update_acl:
@@ -255,9 +258,11 @@ To update only the users list for secret ACL (use PATCH):
 
 Container and Secret ACL(s) update operation are similar except `containers` resource is used
 instead of the `secrets` resource in URI. To get more details on ACL update APIs, you can reference
-the :ref:`Update Secret ACL <put_secret_acl>` , :ref:`Update Container ACL <put_container_acl>`
-, :ref:`Partial Update Secret ACL <patch_secret_acl>` or :ref:`Partial Update Container ACL
-<patch_container_acl>` documentation.
+the `Update Secret ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#put-secret-acl>`__
+, `Update Container ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#put-container-acl>`__
+, `Partial Update Secret ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#patch-secret-acl>`__
+or `Partial Update Container ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#patch-container-acl>`__
+documentation.
 
 
 .. _retrieve_acl:
@@ -320,8 +325,10 @@ To get container ACL data:
     }
 
 
-To get more details on ACL lookup APIs you can reference the :ref:`Get Secret ACL <get_secret_acl>` ,
-:ref:`Get Container ACL <get_container_acl>` documentation.
+To get more details on ACL lookup APIs you can reference the
+`Get Secret ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#get-secret-acl>`__
+, `Get Container ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#get-container-acl>`__
+documentation.
 
 
 .. _delete_acl:
@@ -329,12 +336,15 @@ To get more details on ACL lookup APIs you can reference the :ref:`Get Secret AC
 How to Delete ACL
 #################
 
-ACL defined for a secret or a container can be deleted by using the **DELETE** operation on their respective `acl`
-resource. There is no response content returned on successful deletion.
+ACL defined for a secret or a container can be deleted by using the **DELETE**
+operation on their respective `acl` resource. There is no response content
+returned on successful deletion.
 
-Delete operation removes existing ACL on a secret or a container if there. It can be treated as resetting a secret
-or a container to :ref:`Default ACL<default_implicit_acl>` setting. That's why invoking delete multiple times on
-this resource will not result in error.
+Delete operation removes existing ACL on a secret or a container if there. It
+can be treated as resetting a secret or a container to
+`Default ACL <http://docs.openstack.org/developer/barbican/api/userguide/acls.html#default-implicit-acl>`__
+setting. That's why invoking delete multiple times on this resource will not
+result in error.
 
 .. code-block:: bash
 
@@ -348,5 +358,7 @@ this resource will not result in error.
     200 OK
 
 
-To get more details on ACL delete APIs, you can reference the :ref:`Delete Secret ACL <delete_secret_acl>` ,
-:ref:`Delete Container ACL <delete_container_acl>` documentation.
+To get more details on ACL delete APIs, you can reference the
+`Delete Secret ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#delete-secret-acl>`__
+, `Delete Container ACL <http://docs.openstack.org/developer/barbican/api/reference/acls.html#delete-container-acl>`__
+documentation.

api-guide/source/cas.rst

@@ -18,12 +18,13 @@ certificates which have been signed by another CA maintained by that plugin
 
 The CAs made available to barbican by the plugins are exposed to the client
 through the /cas REST API, which is detailed in the
-:doc:`Certificate Authorities API reference <../reference/cas>`.
+`Certificate Authorities API reference <http://docs.openstack.org/developer/barbican/api/reference/cas.html>`__.
 
 This guide will provide some examples on how to use each of the supported
 operations.  It assumes that you will be using a local running development
 environment of barbican.  If you need assistance with getting set up, please
-reference the :doc:`development guide </setup/dev>`.
+reference the
+`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
 
 .. _listing_the_cas:
 

api-guide/source/certificates.rst

@@ -9,7 +9,8 @@ certificates is implemented.
 
 This guide will provide some examples on how to use each of the supported operations.
 It assumes that you will be using a local running development environment of barbican.
-If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
+If you need assistance with getting set up, please reference the
+`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
 
 Barbican can be used to request certificate issuance from a number of private and
 public Certificate Authorities (CAs).  This is done through the Orders interface.
@@ -163,7 +164,8 @@ A snake-oil CA plugin is included with the barbican source code for basic testin
 In addition, a robust, enterprise-ready CA plugin is provided for the Dogtag CA.
 Instructions for setting up the CA are provided at :doc:`Dogtag Setup Instructions <./dogtag_setup>`.
 
-More details can be found in the :doc:`certificate reference <../reference/certificates>`.
+More details can be found in the
+`certificate reference <http://docs.openstack.org/developer/barbican/api/reference/certificates.html>`__.
 
 .. _order_certificate:
 

api-guide/source/conf.py

@@ -0,0 +1,303 @@
+# -*- coding: utf-8 -*-
+
+# 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.
+#
+# Key Manager API documentation build configuration file
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# import sys
+import subprocess
+
+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 = []
+
+# 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'
+# General information about the project.
+project = u'Key Manager API Guide'
+bug_tag = u'api-guide'
+
+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.
+#
+# The short X.Y version.
+version = '2.1.0'
+# The full version, including alpha/beta/rc tags.
+release = '2.1.0'
+
+# 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'
+
+# 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. Extracted from git log.
+#   bug_tag: Tag for categorizing the bug. Must be set manually.
+#   bug_project: Launchpad project to file bugs against.
+# These variables are passed to the logabug code via html_context.
+giturl = (u"http://git.openstack.org/cgit/openstack/barbican/tree/"
+          "api-guide/source")
+git_cmd = ["/usr/bin/git", "rev-parse", "HEAD"]
+gitsha = subprocess.Popen(
+    git_cmd, stdout=subprocess.PIPE).communicate()[0]
+
+
+# source tree
+pwd = subprocess.Popen(
+    "pwd", stdout=subprocess.PIPE).communicate()[0].strip('\n')
+
+# html_context allows us to pass arbitrary values into the html template
+html_context = {"pwd": pwd,
+                "gitsha": gitsha,
+                "bug_tag": bug_tag,
+                "giturl": giturl,
+                "bug_project": "barbican"}
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# 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.
+# html_theme_options = {}
+
+# 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 = []
+
+# 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 = '%Y-%m-%d %H:%M'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_domain_indices = True
+
+# If false, no index is generated.
+html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'keymanager-api-guide'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    ('index', 'KeyManagerAPI.tex', u'Key Manager API Documentation',
+     u'OpenStack contributors', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'keymanagerapi', u'Key Manager API Documentation',
+     [u'OpenStack contributors'], 1)
+]
+
+# If true, show URL addresses after external links.
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    ('index', 'KeyManagerAPIGuide', u'Key Manager API Guide',
+     u'OpenStack contributors', 'APIGuide',
+     'This guide teaches OpenStack Key Manager service users concepts about '
+     'managing keys in an OpenStack cloud with the Key Manager API.',
+     'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+# texinfo_no_detailmenu = False
+
+# -- Options for Internationalization output ------------------------------
+locale_dirs = ['locale/']
+
+# -- Options for PDF output --------------------------------------------------
+
+pdf_documents = [
+    ('index', u'KeyManagerAPIGuide', u'Key Manager API Guide', u'OpenStack '
+     'contributors')
+]

api-guide/source/consumers.rst

@@ -1,9 +1,10 @@
-*************************
+**************************
 Consumers API - User Guide
-*************************
+**************************
 
 This guide assumes you will be using a local development environment of barbican.
-If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
+If you need assistance with getting set up, please reference the
+`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
 
 
 What is a Consumer?
@@ -100,6 +101,7 @@ the consumers for this container.
 This will return the following response:
 
 .. code-block:: json
+
     {
         "total": 3,
         "next": "http://localhost:9311/v1/consumers?limit=1&offset=2",
@@ -132,6 +134,7 @@ URL which were used when the consumer was created.
 This will return the following response:
 
 .. code-block:: json
+
     {
         "status": "ACTIVE",
         "updated": "2015-10-15T17:56:18.626724",

api-guide/source/containers.rst

@@ -16,7 +16,7 @@ held within. These will be broken down in their respective sections.
 
 This guide will assume you will be using a local running development environment of barbican.
 If you need assistance with getting set up, please reference the
-:doc:`development guide </setup/dev>`.
+`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
 
 .. _generic_containers:
 

api-guide/source/index.rst

@@ -0,0 +1,19 @@
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   secrets
+   secret_metadata
+   containers
+   acls
+   pkcs11keygeneration
+   certificates
+   cas
+   dogtag_setup
+   quotas
+   consumers
+   orders
+

api-guide/source/orders.rst

@@ -13,7 +13,8 @@ The orders resource supports the following types:
 
 This user guide provides high level examples of the orders resource.
 It will assume you will be using a local running development environment of barbican.
-If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
+If you need assistance with getting set up, please reference the
+`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
 
 For a more in depth explanation on how to order a certificate, reference
 the :ref:`How to Order a Certificate <order_certificate>` documentation.
@@ -28,7 +29,9 @@ For an order to be processed correctly the parameters mode,
 bit_length, and algorithm must be valid. Otherwise the order will fail and
 the secret will not be generated. The example below shows a valid order for
 generating a symmetric key. You can find a more detailed explanation about
-the parameters in the :doc:`Orders API <../reference/orders>` documentation.
+the parameters in the
+`Orders API <http://docs.openstack.org/developer/barbican/api/reference/orders.html>`__
+documentation.
 
 .. code-block:: bash
 
@@ -88,7 +91,8 @@ To retrieve the secret generated by the order, refer to the :doc:`Secrets User G
 The order metadata is very useful for determining if your order was processed
 correctly. Since orders are processed asynchronously, you can use the metadata
 returned for the order to verify a successful secret creation.
-The parameters of the response are explained in more detail :ref:`here <get_unique_order_response_attributes>`.
+The parameters of the response are explained in more detail
+`here <http://docs.openstack.org/developer/barbican/api/reference/orders.html#get-unique-order-response-attributes>`__.
 
 .. _retrieve_order_list:
 
@@ -146,9 +150,11 @@ It is also possible to retrieve all orders for a project.
         "total": 2
     }
 
-You can refer to the :ref:`orders parameters <get_order_parameters>` section of
-the :doc:`Orders API <../reference/orders>` documentation in order to
-refine your search among orders.
+You can refer to the
+`orders parameters <http://docs.openstack.org/developer/barbican/api/reference/orders.html#get-order-parameters>`__
+section of the
+`Orders API <http://docs.openstack.org/developer/barbican/api/reference/orders.html>`__
+documentation in order to refine your search among orders.
 
 .. _delete_order:
 

api-guide/source/quotas.rst

@@ -16,7 +16,8 @@ quotas and how a service admin can create, update, read, and delete project quot
 configuration for all projects in his cloud.
 
 This guide will assume you will be using a local running development environment of barbican.
-If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
+If you need assistance with getting set up, please reference the
+`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
 
 .. _user_project_quotas_overview:
 
@@ -101,7 +102,8 @@ with the request.
 
 
 To get more details on the quota lookup API, you can reference the
-:ref:`Get Quotas <get_quotas_request>` documentation.
+`Get Quotas <http://docs.openstack.org/developer/barbican/api/reference/quotas.html#get-quotas-request>`__
+documentation.
 
 
 .. _user_put_project_quotas:
@@ -131,8 +133,9 @@ To set or replace the quotas for the project with the ID 1234:
     HTTP/1.1 204 No Content
 
 
-To get more details on the project quota setting API you can reference
-the :ref:`Set Project Quotas <put_project_quotas>` documentation.
+To get more details on the project quota setting API you can reference the
+`Set Project Quotas <http://docs.openstack.org/developer/barbican/api/reference/quotas.html#put-project-quotas>`__
+documentation.
 
 
 .. _user_get_project_quotas:
@@ -202,8 +205,11 @@ The returned response contains a list with all project quota data.
 
 
 To get more details on project quota lookup APIs you can reference
-the :ref:`Get Project Quota <get_project_quotas_uuid>` and
-:ref:`Get Project Quota List <get_project_quotas>` documentation.
+the
+`Get Project Quota <http://docs.openstack.org/developer/barbican/api/reference/quotas.html#get-project-quotas-uuid>`__
+and
+`Get Project Quota List <http://docs.openstack.org/developer/barbican/api/reference/quotas.html#get-project-quotas>`__
+documentation.
 
 
 .. _user_delete_project_quotas:
@@ -230,4 +236,5 @@ There is no response content returned on successful deletion.
 
 
 To get more details on project quota delete APIs, you can reference the
-:ref:`Delete Project Quotas <delete_project_quotas>` documentation.
+`Delete Project Quotas <http://docs.openstack.org/developer/barbican/api/reference/quotas.html#delete-project-quotas>`__
+documentation.

api-guide/source/secret_metadata.rst

@@ -14,7 +14,8 @@ To create/update the secret metadata for a specific secret, we will need to know
 the secret reference of the secret we wish to add user metadata to. Any metadata
 that was previously set will be deleted and replaced with this metadata.
 For more information on creating/updating secret metadata, you can view the
-:ref:`PUT /v1/secrets/{uuid}/metadata <put_secret_metadata>` section.
+`PUT /v1/secrets/{uuid}/metadata <http://docs.openstack.org/developer/barbican/api/reference/secret_metadata.html#put-secret-metadata>`
+section.
 
 .. code-block:: bash
 

api-guide/source/secrets.rst

@@ -8,7 +8,8 @@ to the secret / keying material stored in the system.
 Barbican supports the storage of data for various content-types securely.
 
 This guide will assume you will be using a local running development environment of barbican.
-If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
+If you need assistance with getting set up, please reference the
+`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
 
 
 What is a Secret?
@@ -25,9 +26,12 @@ Some examples of a secret may include:
   * SSH Keys
 
 For the purpose of this user guide, we will use a simple plaintext
-secret. If you would like to learn more in detail about :ref:`secret parameters <secret_parameters>`,
-:ref:`responses <secret_response_attributes>`, and :ref:`status codes <secret_status_codes>`
-you can reference the :doc:`secret reference <../reference/secrets>`
+secret. If you would like to learn more in detail about
+`secret parameters <http://docs.openstack.org/developer/barbican/api/reference/secrets.html#secret-parameters>`__,
+`responses <http://docs.openstack.org/developer/barbican/api/reference/secrets.html#secret_response_attributes>`__,
+and `status codes <http://docs.openstack.org/developer/barbican/api/reference/secrets.html#secret_status_codes>`__
+you can reference the
+`secret reference <http://docs.openstack.org/developer/barbican/api/reference/secrets.html>`__
 documentation.
 
 
@@ -43,7 +47,9 @@ The first secret we will create is a single step secret. Using a single step,
 barbican expects the user to provide the payload to be stored within the secret
 itself. Once the secret has been created with a payload it cannot be updated. In
 this example we will provide a plain text secret. For more information on creating
-secrets you can view the :ref:`POST /v1/secrets <post_secrets>` section.
+secrets you can view the
+`POST /v1/secrets <http://docs.openstack.org/developer/barbican/api/reference/secrets.html#post-secrets>`__
+section.
 
 .. code-block:: bash
 
@@ -102,7 +108,9 @@ your own in order to update the secret.
 
 No response will be provided. This is expected behavior! If you do receive a
 response, something went wrong and you will have to address that before
-moving forward. (For more information visit :ref:`PUT /v1/secrets/{uuid} <put_secrets>`.)
+moving forward. (For more information visit
+`PUT /v1/secrets/{uuid} <http://docs.openstack.org/developer/barbican/api/reference/secrets.html#put-secrets>`__
+.)
 
 
 .. _retrieve_secret:
@@ -139,4 +147,6 @@ the initial creation (See :ref:`How to Create a Secret <create_secret>`.)
 
 No response will be provided. This is expected behavior! If you do receive a
 response, something went wrong and you will have to address that before
-moving forward. (For more information visit :ref:`DELETE /v1/secrets/{uuid} <delete_secrets>`.)
+moving forward. (For more information visit
+`DELETE /v1/secrets/{uuid} <http://docs.openstack.org/developer/barbican/api/reference/secrets.html#delete-secrets>`__
+.)

doc/source/admin-guide-cloud/access_control.rst

@@ -79,4 +79,5 @@ a secret for which only they have access.   There is also no easy way to grant
 a user access to only a single secret.
 
 To address this limitations the Key Manager service includes an Access
-Control List (ACL) API.  For full details see the :doc:`../api/userguide/acls`
+Control List (ACL) API.  For full details see the
+`ACL API User Guide <http://developer.openstack.org/api-guide/key-manager/acls.html>`__

doc/source/api/index.rst

@@ -5,20 +5,8 @@ Barbican API Documentation
 User Guide
 ##########
 
-.. toctree::
-   :maxdepth: 1
-
-   ./userguide/secrets
-   ./userguide/secret_metadata
-   ./userguide/containers
-   ./userguide/acls
-   ./userguide/pkcs11keygeneration
-   ./userguide/certificates
-   ./userguide/cas
-   ./userguide/dogtag_setup
-   ./userguide/quotas
-   ./userguide/consumers
-   ./userguide/orders
+API guide docs are built to:
+http://developer.openstack.org/api-guide/key-manager/
 
 API Reference
 #############

doc/source/api/reference/acls.rst

@@ -26,7 +26,9 @@ GET /v1/secrets/{uuid}/acl
 ##########################
 Retrieve the ACL settings for a given secret.
 
-If no ACL is defined for that secret, then :ref:`Default ACL<default_implicit_acl>` is returned.
+If no ACL is defined for that secret, then
+`Default ACL <http://developer.openstack.org/api-guide/key-manager/acls.html#default-acl>`__
+is returned.
 
 Request/Response (With ACL defined):
 ************************************
@@ -325,7 +327,9 @@ GET /v1/containers/{uuid}/acl
 #############################
 Retrieve the ACL settings for a given container.
 
-If no ACL is defined for that container, then :ref:`Default ACL<default_implicit_acl>` is returned.
+If no ACL is defined for that container, then
+`Default ACL <http://developer.openstack.org/api-guide/key-manager/acls.html#default-acl>`__
+is returned.
 
 Request/Response (With ACL defined):
 ************************************

doc/source/api/reference/cas.rst

@@ -4,7 +4,7 @@ Certificates Authorities API - Reference
 
 Barbican provides an API to interact with certificate authorities (CAs).  For
 an introduction to CAs and how Barbican manages them, see the
-:doc:`Certificate Authorities User's Guide <../userguide/cas>`.
+`Certificate Authorities User's Guide <http://developer.openstack.org/api-guide/key-manager/cas.html>`__.
 
 Understanding the following concepts, explained in the user's
 guide, is important to understanding how to use this API.
@@ -569,8 +569,9 @@ Any user can request a reference to the preferred CA assigned to his project.  W
 a preferred CA is set for a project, that is the CA that will be used when a user
 of that project requests a certificate and does not specify a CA.  For more
 information, consult the
-:doc:`Certificate Authorities User's Guide <../userguide/cas>` and the
-:doc:`Certificates API User's Guide <../userguide/certificates>`.
+`Certificate Authorities User's Guide <http://developer.openstack.org/api-guide/key-manager/cas.html>`__
+and the
+`Certificates API User's Guide <http://developer.openstack.org/api-guide/key-manager/certificates.html>`__.
 
 .. _get_cas_preferred_request_response:
 
@@ -633,8 +634,9 @@ of the project.  The first created project CA becomes the project's preferred
 CA by default.
 
 For more information, consult the
-:doc:`Certificate Authorities User's Guide <../userguide/cas>` and the
-:doc:`Certificates API User's Guide <../userguide/certificates>`.
+`Certificate Authorities User's Guide <http://developer.openstack.org/api-guide/key-manager/cas.html>`__
+and the
+`Certificates API User's Guide <http://developer.openstack.org/api-guide/key-manager/certificates.html>`__.
 
 .. _post_cas_caid_add_request_response:
 
@@ -886,8 +888,9 @@ requests a certificate and does not specify a CA and his project does not
 have a project preferred CA.
 
 For more information, consult the
-:doc:`Certificate Authorities User's Guide <../userguide/cas>` and the
-:doc:`Certificates API User's Guide <../userguide/certificates>`.
+`Certificate Authorities User's Guide <http://developer.openstack.org/api-guide/key-manager/cas.html>`__
+and the
+`Certificates API User's Guide <http://developer.openstack.org/api-guide/key-manager/certificates.html>`__.
 
 .. _post_cas_caid_set_global_pref_request_response:
 

doc/source/api/reference/certificates.rst

@@ -17,7 +17,7 @@ in the *meta* dictionary.
 
 The result of this operation is an order for a certificate, returned to the client as an order
 reference.  Upon completion, the order will contain a reference to a Certificate Container,
-see :ref:`certificate_containers`.
+see `Certificate Containers <http://developer.openstack.org/api-guide/key-manager/containers.html#certificate-containers>`__.
 
 
 Common Attributes
@@ -99,7 +99,7 @@ Request:
 ********
 
 The request below shows a simple CMC request.  For examples of each type,
-see the :doc:`Certificate User's Guide <../userguide/certificates>`.
+see the `Certificate User's Guide <http://developer.openstack.org/api-guide/key-manager/certificates.html>`.
 
 .. code-block:: javascript
 

doc/source/index.rst

@@ -8,8 +8,8 @@ such as Symmetric Keys, Asymmetric Keys, Certificates and raw binary data.
 Barbican for Users
 ==================
 
-If you're trying to learn how to use barbican, you can start by reading
-about :doc:`Secrets in the Barbican API Guide <api/userguide/secrets>`.
+If you're trying to learn how to use barbican, you can start by reading about
+`Secrets in the Barbican API Guide <http://developer.openstack.org/api-guide/key-manager/secrets.html>`__.
 
 Once you're comfortable working with secrets you can dig into the rest of the
 API.
@@ -59,7 +59,7 @@ will probably want to read:
 .. toctree::
    :maxdepth: 1
 
-   setup
+   setup/index
    admin-guide-cloud/index
 
 This documentation is generated by the Sphinx toolkit and lives in the source

setup.cfg

@@ -54,6 +54,11 @@ all_files = 1
 build-dir = doc/build
 source-dir = doc/source
 
+[build_apiguide]
+all_files = 1
+build-dir = api-guide/build
+source-dir = api-guide/source
+
 [egg_info]
 tag_build =
 tag_date = 0

test-requirements.txt

@@ -21,3 +21,4 @@ bandit>=0.17.3 # Apache-2.0
 sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2 # BSD
 oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0
 reno>=0.1.1 # Apache2
+openstackdocstheme>=1.0.3  # Apache-2.0

tox.ini

@@ -85,7 +85,15 @@ commands =
 
 [testenv:docs]
 commands=
+    rm -rf api-guide/build
     python setup.py build_sphinx
+    sphinx-build -W -b html api-guide/source api-guide/build
+
+[testenv:api-guide]
+# This environment is called from CI scripts to test and publish
+# the API Guide to developer.openstack.org.
+commands =
+  sphinx-build -W -b html -d api-guide/build/doctrees api-guide/source api-guide/build
 
 [testenv:functional]
 # This tox env is purely to make local test development easier