Browse Source
This patch init api-ref document structure and adding some requirements based on the guidance of OpenStack API team. Get ready for os-api-ref sphinx theme change Change-Id: I896c8752fbcf15ec8e5bc6b3862a1ed040936215 Implements: blueprint magnum-doc-rest-apichanges/86/357586/10
11 changed files with 364 additions and 1 deletions
@ -0,0 +1,247 @@
|
||||
# -*- 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. |
||||
# |
||||
# Magnum documentation build configuration file |
||||
# |
||||
# 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 os |
||||
import subprocess |
||||
import sys |
||||
import warnings |
||||
|
||||
# TODO(Graham Hayes): Remove the following block of code when os-api-ref is |
||||
# using openstackdocstheme |
||||
|
||||
import os_api_ref |
||||
|
||||
if getattr(os_api_ref, 'THEME', 'olsosphinx') == 'openstackdocstheme': |
||||
# We are on the new version with openstackdocstheme support |
||||
|
||||
extensions = [ |
||||
'os_api_ref', |
||||
] |
||||
|
||||
import openstackdocstheme # noqa |
||||
|
||||
html_theme = 'openstackdocs' |
||||
html_theme_path = [openstackdocstheme.get_html_theme_path()] |
||||
html_theme_options = { |
||||
"sidebar_mode": "toc", |
||||
} |
||||
|
||||
else: |
||||
# We are on the old version without openstackdocstheme support |
||||
|
||||
extensions = [ |
||||
'os_api_ref', |
||||
'oslosphinx', |
||||
] |
||||
|
||||
# End temporary block |
||||
|
||||
# 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('../../')) |
||||
sys.path.insert(0, os.path.abspath('../')) |
||||
sys.path.insert(0, os.path.abspath('./')) |
||||
|
||||
# -- General configuration ---------------------------------------------------- |
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be |
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. |
||||
|
||||
# The suffix of source filenames. |
||||
source_suffix = '.rst' |
||||
|
||||
# The encoding of source files. |
||||
# |
||||
# source_encoding = 'utf-8' |
||||
|
||||
# The master toctree document. |
||||
master_doc = 'index' |
||||
|
||||
# General information about the project. |
||||
project = u'Container Infrastructure Management API Reference' |
||||
copyright = u'2010-present, OpenStack Foundation' |
||||
|
||||
# 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. |
||||
# |
||||
from magnum.version import version_info |
||||
# The full version, including alpha/beta/rc tags. |
||||
release = version_info.release_string() |
||||
# The short X.Y version. |
||||
version = version_info.version_string() |
||||
|
||||
# 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' |
||||
|
||||
# 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 = False |
||||
|
||||
# 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' |
||||
|
||||
# -- Options for man page output ---------------------------------------------- |
||||
|
||||
# Grouping the document tree for man pages. |
||||
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' |
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------- |
||||
|
||||
# The theme to use for HTML and HTML Help pages. Major themes that come with |
||||
# Sphinx are currently 'default' and 'sphinxdoc'. |
||||
# html_theme_path = ["."] |
||||
# html_theme = '_theme' |
||||
|
||||
# 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 = [] |
||||
|
||||
# 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'] |
||||
|
||||
# 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' |
||||
git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", |
||||
"-n1"] |
||||
try: |
||||
html_last_updated_fmt = subprocess.Popen( |
||||
git_cmd, stdout=subprocess.PIPE).communicate()[0].decode() |
||||
except Exception: |
||||
warnings.warn('Cannot get last updated time from git repository. ' |
||||
'Not setting "html_last_updated_fmt".') |
||||
|
||||
# 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_use_modindex = 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, 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 = '' |
||||
|
||||
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). |
||||
# html_file_suffix = '' |
||||
|
||||
# Output file base name for HTML help builder. |
||||
htmlhelp_basename = 'magnumdoc' |
||||
|
||||
|
||||
# -- Options for LaTeX output ------------------------------------------------- |
||||
|
||||
# The paper size ('letter' or 'a4'). |
||||
# latex_paper_size = 'letter' |
||||
|
||||
# The font size ('10pt', '11pt' or '12pt'). |
||||
# latex_font_size = '10pt' |
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples |
||||
# (source start file, target name, title, author, documentclass |
||||
# [howto/manual]). |
||||
latex_documents = [ |
||||
('index', 'Magnum.tex', |
||||
u'OpenStack Container Infrastructure Management API Documentation', |
||||
u'OpenStack Foundation', '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 |
||||
|
||||
# Additional stuff for the LaTeX preamble. |
||||
# latex_preamble = '' |
||||
|
||||
# Documents to append as an appendix to all manuals. |
||||
# latex_appendices = [] |
||||
|
||||
# If false, no module index is generated. |
||||
# latex_use_modindex = True |
@ -0,0 +1,14 @@
|
||||
:tocdepth: 2 |
||||
|
||||
======================================== |
||||
Container Infrastructure Management API |
||||
======================================== |
||||
|
||||
.. rest_expand_all:: |
||||
|
||||
.. include:: versions.inc |
||||
.. include:: urls.inc |
||||
.. include:: bays_clusters.inc |
||||
.. include:: baymodels_clustertemplates.inc |
||||
.. include:: certificates.inc |
||||
.. include:: mservices.inc |
@ -0,0 +1,62 @@
|
||||
################# |
||||
# Success Codes # |
||||
################# |
||||
200: |
||||
default: | |
||||
Request was successful. |
||||
201: |
||||
default: | |
||||
Resource was created and is ready to use. |
||||
202: |
||||
default: | |
||||
Request was accepted for processing, but the processing has not been |
||||
completed. A 'location' header is included in the response which contains |
||||
a link to check the progress of the request. |
||||
204: |
||||
default: | |
||||
The server has fulfilled the request by deleting the resource. |
||||
300: |
||||
default: | |
||||
There are multiple choices for resources. The request has to be more |
||||
specific to successfully retrieve one of these resources. |
||||
302: |
||||
default: | |
||||
The response is about a redirection hint. The header of the response |
||||
usually contains a 'location' value where requesters can check to track |
||||
the real location of the resource. |
||||
|
||||
################# |
||||
# Error Codes # |
||||
################# |
||||
|
||||
400: |
||||
default: | |
||||
Some content in the request was invalid. |
||||
resource_signal: | |
||||
The target resource doesn't support receiving a signal. |
||||
401: |
||||
default: | |
||||
User must authenticate before making a request. |
||||
403: |
||||
default: | |
||||
Policy does not allow current user to do this operation. |
||||
404: |
||||
default: | |
||||
The requested resource could not be found. |
||||
405: |
||||
default: | |
||||
Method is not valid for this endpoint. |
||||
409: |
||||
default: | |
||||
This operation conflicted with another operation on this resource. |
||||
duplcate_zone: | |
||||
There is already a zone with this name. |
||||
500: |
||||
default: | |
||||
Something went wrong inside the service. This should not happen usually. |
||||
If it does happen, it means the server has experienced some serious |
||||
problems. |
||||
503: |
||||
default: | |
||||
Service is not available. This is mostly caused by service configuration |
||||
errors which prevents the service from successful start up. |
@ -0,0 +1,31 @@
|
||||
.. -*- rst -*- |
||||
|
||||
================= |
||||
Magnum Base URLs |
||||
================= |
||||
|
||||
All API calls through the rest of this document require authentication |
||||
with the OpenStack Identity service. They also required a ``url`` that |
||||
is extracted from the Identity token of type |
||||
``container-infra``. This will be the root url that every call below will be |
||||
added to build a full path. |
||||
|
||||
Note that if using OpenStack Identity service API v2, ``url`` can be |
||||
represented via ``adminURL``, ``internalURL`` or ``publicURL`` in endpoint |
||||
catalog. In Identity service API v3, ``url`` is represented with field |
||||
``interface`` including ``admin``, ``internal`` and ``public``. |
||||
|
||||
For instance, if the ``url`` is |
||||
``http://my-container-infra.org/magnum/v1`` then the full API call for |
||||
``/clusters`` is ``http://my-container-infra.org/magnum/v1/clusters``. |
||||
|
||||
Depending on the deployment the container infrastructure management service |
||||
url might be http or https, a custom port, a custom path, and include your |
||||
project id. The only way to know the urls for your deployment is by using the |
||||
service catalog. The container infrastructure management URL should never be |
||||
hard coded in applications, even if they are only expected to work at a |
||||
single site. It should always be discovered from the Identity token. |
||||
|
||||
As such, for the rest of this document we will be using short hand |
||||
where ``GET /clusters`` really means |
||||
``GET {your_container_infra_url}/clusters``. |
Loading…
Reference in new issue