diff --git a/AUTHORS b/AUTHORS index c24661ba5..9a87fb43e 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,5 +1,7 @@ +Andrea Adams Andreas Jaeger Angelo Mendonca +Anh Tran Artur Basiak Ben Motz Bertrand Lallau @@ -7,17 +9,25 @@ Brad Klein Cao Xuan Hoang Clenimar Filemon Craig Bryant +Craig Bryant +Darren Hague David C Kennedy David C Kennedy +Deepak Deklan Dieterly Deklan Dieterly Deklan Dieterly Derrick Johnson Derrick Johnson Dexter Fryar +Dirk Mueller Dobroslaw Zybort +Emma Foley Erickson Santos +Flavio Percoco +Flávio Ramalho Ghanshyam +Habeeb Mohammed Haiwei Xu Hironori Shiina Igor Natanael @@ -29,6 +39,8 @@ Joe Keen Jonathan Halterman Jonathan Halterman Kaiyan Sheng +Kamil Choroba +Ken'ichi Ohmichi Koji Nakazono Laszlo Hegedus LiuNanke @@ -40,6 +52,7 @@ Michael James Hoppal Michal Zielonka Monty Taylor Nam Nguyen Hoai +Pradeep Kumar Velusamy Rob Raymond Rodolfo Alonso Hernandez Roland Hochmuth @@ -48,13 +61,17 @@ Ryan Brandt SamKirsch10 Shinya Kawabata Srinivas Sakhamuri +Stefano Canepa +Steve Simpson Swapnil Kulkarni (coolsvap) +Thomas Bechtold Thomas Graichen Tim Kuhlman Tomasz Trębski Tomasz Trębski Tong Li Victor Ion Munteanu +Vu Cong Tuan Witold Bedyk Yushiro FURUKAWA ZhiQiang Fan @@ -63,13 +80,19 @@ bklei cindy oneill dieterly gary-hessler +gecong1973 haali1 henriquetruta hochmuth +ji-xuepeng kaiyan-sheng liu-sheng +liyingjun +loooosy melissaml oiskam1 +pallavi raymondr +roland-hochmuth satsuki_fukazu venkatamahesh diff --git a/api-ref/locale/.gitkeep b/api-ref/locale/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py new file mode 100644 index 000000000..32657b810 --- /dev/null +++ b/api-ref/source/conf.py @@ -0,0 +1,217 @@ +# 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. + +from monasca_api.version import version_info + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.6' + +# 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', + 'openstackdocstheme' +] + +# 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' + +# The master toctree document. +master_doc = 'index' + +# General details about project +repository_name = u'openstack/monasca-api' +project = u'Monitoring API Reference' +version = version_info.canonical_version_string() +release = version_info.version_string_with_vcs() +bug_project = u'863' +bug_tag = u'' +copyright = u'2014-present, OpenStack Foundation' +author = u'OpenStack Foundation' + +# 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 = [] + +# 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' + +# 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"} + +# A shorter title for the navigation bar. Default is the same as html_title. +html_short_title = 'API Ref' + +# 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 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 = 'MonitoringApiRefDoc' + +# -- 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 = [ + (master_doc, 'MonitoringApiRef.tex', u'Monitoring Service API Reference', + [author], '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 Internationalization output ------------------------------ +locale_dirs = ['locale/'] diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst new file mode 100644 index 000000000..bb7ae082b --- /dev/null +++ b/api-ref/source/index.rst @@ -0,0 +1,22 @@ +:tocdepth: 2 + +.. + Copyright 2017 Fujitsu LIMITED + + 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. + +======================= +Monitoring Service APIs +======================= + +.. rest_expand_all:: diff --git a/doc/api-samples/.gitkeep b/doc/api-samples/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/doc/api-samples/empty.json b/doc/api-samples/empty.json new file mode 100644 index 000000000..c267aa9bd --- /dev/null +++ b/doc/api-samples/empty.json @@ -0,0 +1,3 @@ +{ + "test": {} +} diff --git a/doc/source/.gitkeep b/doc/source/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst new file mode 100644 index 000000000..4b1b94ad4 --- /dev/null +++ b/doc/source/admin/index.rst @@ -0,0 +1,6 @@ +==================== +Administration guide +==================== + +.. toctree:: + :maxdepth: 2 diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 000000000..3c592a291 --- /dev/null +++ b/doc/source/cli/index.rst @@ -0,0 +1,4 @@ +====================== +Command Line Interface +====================== + diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 000000000..c5f54e0c9 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,253 @@ +# -*- coding: utf-8 -*- +# +# monasca-api documentation build configuration file, created by +# sphinx-quickstart on Wed Nov 18 12:02:03 2015. +# +# 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 sys + +from monasca_api.version import version_info + +sys.path = [ + os.path.abspath('../..'), + os.path.abspath('../../bin') +] + sys.path + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.6' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.coverage', + 'sphinx.ext.ifconfig', + 'sphinx.ext.graphviz', + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + # TODO(trebskit) enable as soon as we get configgen in place + # 'oslo_config.sphinxconfiggen' + # 'oslo_config.sphinxext', + 'openstackdocstheme', +] + +# geeneral information about project +repository_name = u'openstack/monasca-api' +project = u'monasca' +version = version_info.canonical_version_string() +release = version_info.version_string_with_vcs() +bug_project = u'863' +bug_tag = u'' +copyright = u'2014-present, OpenStack Foundation' +author = u'OpenStack Foundation' + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [ + 'common', + 'doc', + 'documentation', + 'etc', + 'java' +] + +# 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 = True + +# 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 = ['monasca_api.', 'monasca'] + +# -- 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 = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v 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 +# doc. 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 false, no module index is generated. +html_use_modindex = 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 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 + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'MonitoringApiDoc' + +# -- 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': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# 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 = [ + (master_doc, 'MonitoringApi.tex', u'Monasca Documentation', + [author], '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 = [ + (master_doc, 'monitoringapi', u'Monasca Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://doc.python.org/': None} diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 000000000..e5cda699e --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,3 @@ +============= +Configuration +============= diff --git a/doc/source/contributor/.gitignore b/doc/source/contributor/.gitignore new file mode 100644 index 000000000..13f025dd0 --- /dev/null +++ b/doc/source/contributor/.gitignore @@ -0,0 +1,3 @@ +# codebase documentation is autogenerated +# do not track it +api/ diff --git a/doc/source/contributor/code.rst b/doc/source/contributor/code.rst new file mode 100644 index 000000000..f8fa03f65 --- /dev/null +++ b/doc/source/contributor/code.rst @@ -0,0 +1,18 @@ +.. _codedocs: + +====================== +Codebase documentation +====================== + +Following section contains codebase documenation generated with, a little +bit of assistance, `sphinx.ext.autodoc`_. + +.. _`sphinx.ext.autodoc`: http://www.sphinx-doc.org/en/stable/ext/autodoc.html + +Modules +======= + +.. toctree:: + :maxdepth: 2 + + api/autoindex.rst diff --git a/doc/source/contributor/history.rst b/doc/source/contributor/history.rst new file mode 100644 index 000000000..f69be70b3 --- /dev/null +++ b/doc/source/contributor/history.rst @@ -0,0 +1 @@ +.. include:: ../../../ChangeLog diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 000000000..6bf4032d8 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,37 @@ +======================= +Contribution Guidelines +======================= + +In the Contributions Guide, you will find documented policies for +developing with monasca-api. This includes the processes we use for +blueprints and specs, bugs, contributor onboarding, core reviewer +memberships, and other procedural items. + +monasca-api, as with all OpenStack projects, is written with the following +design guidelines in mind: + +* **Component based architecture**: Quickly add new behaviors +* **Highly available**: Scale to very serious workloads +* **Fault tolerant**: Isolated processes avoid cascading failures +* **Recoverable**: Failures should be easy to diagnose, debug, and rectify +* **Open standards**: Be a reference implementation for a community-driven api + +This documentation is generated by the Sphinx toolkit and lives in the source +tree. Additional documentation on monasca-api and other components of +OpenStack can be found on the `OpenStack wiki `_. + +Developer reference +------------------- + +.. toctree:: + :maxdepth: 1 + + code + +Changelog +--------- + +.. toctree:: + :maxdepth: 1 + + history diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst new file mode 100644 index 000000000..fa106d194 --- /dev/null +++ b/doc/source/glossary.rst @@ -0,0 +1,3 @@ +======== +Glossary +======== diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 000000000..024f27f01 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,51 @@ +.. + monasca-api documentation master file + Copyright 2017 FUJITSU LIMITED + + 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. + +=================================== +Welcome to Monasca's documentation! +=================================== + +Monasca is a open-source multi-tenant, highly scalable, performant, +fault-tolerant monitoring-as-a-service solution that +integrates with OpenStack. It uses a REST API for high-speed metrics +processing and querying and has a streaming +alarm and notification engine. + +The developer documentation provided here is continually kept up-to-date +based on the latest code, and may not represent the state of the project at +any specific prior release. + +.. note:: This is documentation for developers, if you are looking for more + general documentation including API, install, operator and user + guides see `docs.openstack.org`_ + +.. _`docs.openstack.org`: https://docs.openstack.org + +.. toctree:: + :maxdepth: 2 + + user/index + admin/index + install/index + configuration/index + cli/index + contributor/index + +.. toctree:: + :maxdepth: 1 + + glossary + diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 000000000..eeb01df82 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,6 @@ +============ +Installation +============ + +.. toctree:: + :maxdepth: 2 diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 000000000..8da48ac21 --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,6 @@ +========== +User guide +========== + +.. toctree:: + :maxdepth: 2 diff --git a/monasca_api/common/repositories/exceptions.py b/monasca_api/common/repositories/exceptions.py index 1de610051..2bdb6ee0d 100644 --- a/monasca_api/common/repositories/exceptions.py +++ b/monasca_api/common/repositories/exceptions.py @@ -28,5 +28,11 @@ class UnsupportedDriverException(Exception): pass -__all__ = (AlreadyExistsException, DoesNotExistException, InvalidUpdateException, - RepositoryException, MultipleMetricsException, UnsupportedDriverException) +__all__ = ( + 'AlreadyExistsException', + 'DoesNotExistException', + 'InvalidUpdateException', + 'RepositoryException', + 'MultipleMetricsException', + 'UnsupportedDriverException' +) diff --git a/monasca_api/v2/reference/helpers.py b/monasca_api/v2/reference/helpers.py index fd48f76f5..711724d3e 100644 --- a/monasca_api/v2/reference/helpers.py +++ b/monasca_api/v2/reference/helpers.py @@ -76,8 +76,9 @@ def validate_authorization(req, authorized_roles): different set of roles). :param req: HTTP request object. Must contain "X-ROLES" in the HTTP - request header. + request header. :param authorized_roles: List of authorized roles to check against. + :raises falcon.HTTPUnauthorized """ roles = req.roles @@ -103,7 +104,8 @@ def get_x_tenant_or_tenant_id(req, delegate_authorized_roles): :param req: HTTP request object. :param delegate_authorized_roles: List of authorized roles that have - delegate privileges. + delegate privileges. + :returns: Returns the cross tenant or tenant ID. """ if any(x in set(delegate_authorized_roles) for x in req.roles): diff --git a/monasca_api/version.py b/monasca_api/version.py new file mode 100644 index 000000000..4b04b7a37 --- /dev/null +++ b/monasca_api/version.py @@ -0,0 +1,18 @@ +# Copyright 2017 FUJITSU LIMITED +# +# 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. + +import pbr.version + +version_info = pbr.version.VersionInfo('monasca-api') +version_str = version_info.version_string() diff --git a/releasenotes/locale/.gitkeep b/releasenotes/locale/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/releasenotes/notes/os-docs-550ce9ad68a4a29e.yaml b/releasenotes/notes/os-docs-550ce9ad68a4a29e.yaml new file mode 100644 index 000000000..2574c80d3 --- /dev/null +++ b/releasenotes/notes/os-docs-550ce9ad68a4a29e.yaml @@ -0,0 +1,7 @@ +--- + +upgrade: + - Documentation handling of monasca-api has been migrated + to match OpenStack process. Note that this is just + initial migration and entire transition will be completed + in future. diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py new file mode 100644 index 000000000..4733a41ed --- /dev/null +++ b/releasenotes/source/conf.py @@ -0,0 +1,228 @@ +# 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. + +from monasca_api.version import version_info + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.6' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'openstackdocstheme', + 'reno.sphinxext' +] + +# 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' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +repository_name = u'openstack/monasca-api' +project = u'Monitoring API Release Notes' +version = version_info.canonical_version_string() +release = version_info.version_string_with_vcs() +bug_project = u'863' +bug_tag = u'' +copyright = u'2014-present, OpenStack Foundation' +author = u'OpenStack Foundation' + +# 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 = [] + +# 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 = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v 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 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 = 'MonitoringApiReleaseNotesDoc' + +# -- 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 = [( + master_doc, 'MonitoringApiReleaseNotes.tex', + u'Monitoring API Release Notes', [author], + '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 = [ + (master_doc, 'monitoringapireleasenotes', + u'Monitoring API Release Notes', [author], + 1) +] + +# -- Options for Internationalization output ------------------------------ +locale_dirs = ['locale/'] diff --git a/releasenotes/source/index.rst b/releasenotes/source/index.rst new file mode 100644 index 000000000..8aa6a1d5c --- /dev/null +++ b/releasenotes/source/index.rst @@ -0,0 +1,10 @@ +============================ +Monitoring API Release Notes +============================ + +Contents: + +.. toctree:: + :maxdepth: 1 + + unreleased diff --git a/releasenotes/source/unreleased.rst b/releasenotes/source/unreleased.rst new file mode 100644 index 000000000..cd22aabcc --- /dev/null +++ b/releasenotes/source/unreleased.rst @@ -0,0 +1,5 @@ +============================== + Current Series Release Notes +============================== + +.. release-notes:: diff --git a/setup.cfg b/setup.cfg index 33f5f5675..f97e57e93 100644 --- a/setup.cfg +++ b/setup.cfg @@ -35,5 +35,34 @@ console_scripts = tempest.test_plugins = monasca_tests = monasca_tempest_tests.plugin:MonascaTempestPlugin +[build_sphinx] +all_files = 1 +build-dir = doc/build +source-dir = doc/source +warning-is-error = 1 + +[build_apiref] +all_files = 1 +build-dir = api-ref/build +source-dir = api-ref/source + +[build_releasenotes] +all_files = 1 +build-dir = releasenotes/build +source-dir = releasenotes/source + +[egg_info] +tag_build = +tag_date = 0 +tag_svn_revision = 0 + +[wheel] +universal = 1 + [pbr] -warnerrors = True +autodoc_index_modules = True +autodoc_exclude_modules = + monasca_api.api.wsgi* + monasca_api.tests.* + monasca_tempest_tests.* +api_doc_dir = contributor/api diff --git a/test-requirements.txt b/test-requirements.txt index 7dfeeffeb..0ed582524 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -17,7 +17,16 @@ mox>=0.5.3 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0 os-testr>=0.8.0 # Apache-2.0 python-subunit>=0.0.18 # Apache-2.0/BSD + +# tempest testrepository>=0.0.18 # Apache-2.0/BSD testscenarios>=0.4 # Apache-2.0/BSD testtools>=1.4.0 # MIT tempest-lib>=0.14.0 # Apache-2.0 + +# documentation +doc8 # Apache-2.0 +sphinx>=1.6.2 # BSD +os-api-ref>=1.0.0 # Apache-2.0 +reno!=2.3.1,>=1.8.0 # Apache-2.0 +openstackdocstheme>=1.16.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index 4d078f273..f615b4a39 100644 --- a/tox.ini +++ b/tox.ini @@ -73,6 +73,55 @@ commands = {[testenv:flake8]commands} {[testenv:bandit]commands} {[testenv:bashate]commands} + {[testenv:checkniceness]commands} + +[testenv:docs] +description = Builds api-ref, api-guide, releasenotes and devdocs +commands = + {[testenv:devdocs]commands} + {[testenv:api-ref]commands} + {[testenv:releasenotes]commands} + +[testenv:api-ref] +description = Called from CI scripts to test and publish the API Ref +commands = + rm -rf api-ref/build + {[testenv:checkjson]commands} + sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html + +[testenv:releasenotes] +description = Called from CI script to test and publish the Release Notes +commands = + rm -rf releasenotes/build + sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html + +[testenv:devdocs] +description = Builds developer documentation +commands = + rm -rf doc/build + {[testenv:checkjson]commands} + python setup.py build_sphinx + +[testenv:checkniceness] +skip_install = True +usedevelop = False +description = Validates (pep-like) documenation +commands = + doc8 --file-encoding utf-8 {toxinidir}/doc + doc8 --file-encoding utf-8 {toxinidir}/api-ref + doc8 --file-encoding utf-8 {toxinidir}/releasenotes + +[testenv:checkjson] +description = Validates all json samples inside doc folder +deps = +skip_install = True +usedevelop = False +whitelist_externals = + python + bash +commands = + bash -c "! find doc/ -type f -name *.json | xargs grep -U -n $'\r'" + bash -c '! find doc/ -type f -name *.json | xargs -t -n1 python -m json.tool 2>&1 > /dev/null | grep -B1 -v ^python' [testenv:venv] commands = {posargs}