Rearranges to create new Compute API Guide

Uses openstackdocstheme to match other content

Has a dependent change in project-config also so that
file will build to developer.openstack.org/compute
at https://review.openstack.org/#/c/231000/

Change-Id: Ic060a1e79e4b2f8695cb788ff4df018e0cfd3286
This commit is contained in:
Anne Gentle 2015-10-01 17:27:50 -05:00 committed by John Garbutt
parent ea23e252f8
commit 17961c41a3
20 changed files with 335 additions and 22 deletions

1
.gitignore vendored
View File

@ -29,6 +29,7 @@ covhtml
dist/*
doc/source/api/*
doc/build/*
api-guide/build/*
etc/nova/nova.conf.sample
instances
keeper

295
api-guide/source/conf.py Normal file
View File

@ -0,0 +1,295 @@
# -*- 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.
#
# Compute API documentation build configuration file
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# 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 = []
# 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'Compute API Guide'
bug_tag = u'api-guide'
copyright = u'2015, 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.
# These variables are passed to the logabug code via html_context.
giturl = u'http://git.openstack.org/cgit/openstack/nova/tree/api-guide/source'
git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '"
gitsha = os.popen(git_cmd).read().strip('\n')
# source tree
pwd = os.popen("pwd").read().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}
# 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 = 'compute-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', 'ComputeAPI.tex', u'Compute 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', 'computeapi', u'Compute 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', 'ComputeAPIGuide', u'Compute API Guide',
u'OpenStack contributors', 'APIGuide',
'This guide teaches OpenStack Compute service users concepts about '
'managing resources in an OpenStack cloud with the Compute 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'ComputeAPIGuide', u'Compute API Guide', u'OpenStack '
'contributors')
]

View File

@ -31,7 +31,7 @@ several key concepts:
is also required.
For more details, such as server actions and server metadata,
please see: :doc:`2.0_server_concepts`
please see: :doc:`server_concepts`
- **Flavor**

View File

@ -1,5 +1,5 @@
..
Copyright 2009-2014 OpenStack Foundation
Copyright 2009-2015 OpenStack Foundation
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
@ -17,16 +17,16 @@
Compute API
===========
OpenStack Nova has a ReSTful HTTP service called the OpenStack Compute API.
Through this API, Nova provides massively scalable, on demand, self service
access to compute resources. Depending on the deployment those compute
resources might be Virtual Machines, Physical Machines or Containers.
The nova project has a ReSTful HTTP service called the OpenStack Compute API.
Through this API, the service provides massively scalable, on demand,
self-service access to compute resources. Depending on the deployment those
compute resources might be Virtual Machines, Physical Machines or Containers.
We welcome feedback, comments, and bug reports at
`bugs.launchpad.net/nova <http://bugs.launchpad.net/nova>`__.
Intended Audience
Intended audience
=================
This guide assists software developers who want to develop applications
@ -64,7 +64,7 @@ please read:
microversions
Key API Concepts
Key API concepts
================
The following documents go into more details about the key concepts of the
@ -73,8 +73,8 @@ OpenStack Compute API:
.. toctree::
:maxdepth: 2
2.0_general_info
2.0_server_concepts
general_info
server_concepts
authentication
faults
limits
@ -84,11 +84,9 @@ OpenStack Compute API:
request_and_response_formats
Full Reference
Full reference
==============
For a full reference listing for the OpenStack Compute API, please see:
* `*Compute API v2.1 extensions (CURRENT)* <http://developer.openstack.org/api-ref-compute-v2.1.html>`__.
* `*Compute API v2 reference (SUPPORTED)* <http://developer.openstack.org/api-ref-compute-v2.html>`__.
* `*Compute API v2 extensions (SUPPORTED)* <http://developer.openstack.org/api-ref-compute-v2-ext.html>`__.
* `*Compute API reference (CURRENT)* <http://developer.openstack.org/api-ref-compute-v2.1.html>`__.

View File

@ -1,5 +1,14 @@
OpenStack Nova Documentation README
===================================
See the "Building the Documentation" section of
Both contributor developer documentation and
REST API documentation are sourced here.
Contributor developer docs are built to:
http://docs.openstack.org/developer/nova/
API guide docs are built to:
http://developer.openstack.org/api-guide/compute/
For more details, see the "Building the Documentation" section of
doc/source/development.environment.rst.

View File

@ -58,17 +58,14 @@ Changes to the Compute API post v2.1 are made using microversions. You can see a
api_microversion_history
We also have a local copy of the v2 docs:
.. toctree::
:maxdepth: 1
v2/index
We also publish end-user API docs as an API Guide.
* `Compute API Guide`_
.. _`v2.1 (CURRENT)`: http://developer.openstack.org/api-ref-compute-v2.1.html
.. _`v2 (SUPPORTED)`: http://developer.openstack.org/api-ref-compute-v2.html
.. _`v2 extensions (SUPPORTED)`: http://developer.openstack.org/api-ref-compute-v2-ext.html
.. _`Compute API Guide`: http://developer.openstack.org/api-guide/compute/
There was a session on the v2.1 API at the Liberty summit which you can watch
`here <https://www.openstack.org/summit/vancouver-2015/summit-videos/presentation/introduction-of-a-new-nova-rest-api-why-we-need-to-use-nova-v2-1-api>`_.

View File

@ -196,6 +196,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

View File

@ -22,6 +22,7 @@ testresources>=0.2.4
testtools>=1.4.0
tempest-lib>=0.10.0
bandit>=0.13.2
openstackdocstheme>=1.0.3
# vmwareapi driver specific dependencies
oslo.vmware>=1.16.0 # Apache-2.0

View File

@ -104,10 +104,17 @@ commands = {posargs}
[testenv:docs]
commands =
rm -rf doc/source/api doc/build
rm -rf doc/source/api doc/build api-guide/build
python setup.py build_sphinx
bash -c '! find doc/ -type f -name *.json | xargs -t -n1 python -m json.tool 2>&1 > /dev/null | grep -B1 -v ^python'
oslo-config-generator --config-file=etc/nova/nova-config-generator.conf
sphinx-build -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 -b html -d api-guide/build/doctrees api-guide/source api-guide/build
[testenv:docs-constraints]
install_command = {[testenv:common-constraints]install_command}