os-api-ref-0.3.0/000077500000000000000000000000001272425777700135005ustar00rootroot00000000000000os-api-ref-0.3.0/.coveragerc000066400000000000000000000001451272425777700156210ustar00rootroot00000000000000[run] branch = True source = os_api_ref omit = os_api_ref/openstack/* [report] ignore_errors = True os-api-ref-0.3.0/.gitignore000066400000000000000000000007431272425777700154740ustar00rootroot00000000000000*.py[cod] # C extensions *.so # Packages *.egg* *.egg-info dist build eggs parts bin var sdist develop-eggs .installed.cfg lib lib64 # Installer logs pip-log.txt # Unit test / coverage reports cover/ .coverage* !.coveragerc .tox nosetests.xml .testrepository .venv # Translations *.mo # Mr Developer .mr.developer.cfg .project .pydevproject # Complexity output/*.html output/*/index.html # Sphinx doc/build # pbr generates these AUTHORS ChangeLog # Editors *~ .*.swp .*sw? os-api-ref-0.3.0/.gitreview000066400000000000000000000001171272425777700155050ustar00rootroot00000000000000[gerrit] host=review.openstack.org port=29418 project=openstack/os-api-ref.git os-api-ref-0.3.0/.mailmap000066400000000000000000000001311272425777700151140ustar00rootroot00000000000000# Format is: # # os-api-ref-0.3.0/.testr.conf000066400000000000000000000004771272425777700155760ustar00rootroot00000000000000[DEFAULT] test_command=OS_STDOUT_CAPTURE=${OS_STDOUT_CAPTURE:-1} \ OS_STDERR_CAPTURE=${OS_STDERR_CAPTURE:-1} \ OS_TEST_TIMEOUT=${OS_TEST_TIMEOUT:-60} \ ${PYTHON:-python} -m subunit.run discover -t ./ . $LISTOPT $IDOPTION test_id_option=--load-list $IDFILE test_list_option=--list os-api-ref-0.3.0/CONTRIBUTING.rst000066400000000000000000000012271272425777700161430ustar00rootroot00000000000000If you would like to contribute to the development of OpenStack, you must follow the steps in this page: http://docs.openstack.org/infra/manual/developers.html If you already have a good understanding of how the system works and your OpenStack accounts are set up, you can skip to the development workflow section of this documentation to learn how changes to OpenStack should be submitted for review via the Gerrit tool: http://docs.openstack.org/infra/manual/developers.html#development-workflow Pull requests submitted through GitHub will be ignored. Bugs should be filed on Launchpad, not GitHub: https://bugs.launchpad.net/openstack-doc-tools os-api-ref-0.3.0/HACKING.rst000066400000000000000000000002421272425777700152740ustar00rootroot00000000000000os-api-ref Style Commandments =============================================== Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/ os-api-ref-0.3.0/LICENSE000066400000000000000000000236371272425777700145200ustar00rootroot00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. os-api-ref-0.3.0/MANIFEST.in000066400000000000000000000001361272425777700152360ustar00rootroot00000000000000include AUTHORS include ChangeLog exclude .gitignore exclude .gitreview global-exclude *.pyc os-api-ref-0.3.0/README.rst000066400000000000000000000040341272425777700151700ustar00rootroot00000000000000os-api-ref ========== Sphinx Extensions to support API reference sites in OpenStack This project is a collection of sphinx stanzas that assist in building an API Reference site for an OpenStack project in RST. RST is great for unstructured English, but displaying semi structured (and repetitive) data in tables is not it's strength. This provides tooling to insert semi-structured data describing request and response parameters, and turn those into nice tables. The project also includes a set of styling (and javascript) that is expected to layer on top of an ``oslosphinx`` theme base. This provides a nice set of collapsing sections for REST methods and javascript controls to expand / collapse all sections. Features -------- * 2 new sphinx stanzas ``rest_method`` and ``rest_parameters`` which support putting semi-structured data into the RST files. TODO ---- A list, in no particular order, of things we should do in this project. If you would like to contribute to any of these please show up in ``#openstack-dev`` on IRC and ask for ``sdague`` to discuss. * Enhance documentation with examples and best practices * Testing for the code * ``max_microversion`` parameter support - so that we automatically tag parameters that have been removed * microversion selector, so that you can get a version of the api-ref that hides all microversion elements beyond your selected version (this one is going to be a bit of complex javascript) * make this compatible with openstackdocstheme (which is equal parts work here and with the openstack docs theme). Potential ideas ~~~~~~~~~~~~~~~ These aren't even quite todos, but just ideas about things that might be useful. * ``.. literalinclude`` is good for API samples files to be included, but should we have more markup that includes the full ``REST /URL`` as well Sphinx stanzas -------------- TODO: document the details of the stanzas * Free software: Apache license * Documentation: http://docs.openstack.org/developer/os-api-ref * Source: http://git.openstack.org/cgit/openstack/os-api-ref os-api-ref-0.3.0/TESTS.rst000066400000000000000000000005221272425777700151330ustar00rootroot00000000000000============================== Tests that should be written ============================== Negative * test warning when groups are out of order * test when parameter keys are missing * test when description RST is invalid * test when parameter file is missing Microversion * test attributes are set when microversions are annotated. os-api-ref-0.3.0/babel.cfg000066400000000000000000000000211272425777700152170ustar00rootroot00000000000000[python: **.py] os-api-ref-0.3.0/doc/000077500000000000000000000000001272425777700142455ustar00rootroot00000000000000os-api-ref-0.3.0/doc/source/000077500000000000000000000000001272425777700155455ustar00rootroot00000000000000os-api-ref-0.3.0/doc/source/conf.py000077500000000000000000000046261272425777700170570ustar00rootroot00000000000000# -*- 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. import os import sys 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. extensions = [ 'sphinx.ext.autodoc', #'sphinx.ext.intersphinx', 'oslosphinx' ] # autodoc generation is a bit aggressive and a nuisance when doing heavy # text edit cycles. # execute "export SPHINX_DEBUG=1" in your terminal to disable # The suffix of source filenames. source_suffix = '.rst' # The master toctree document. master_doc = 'index' # General information about the project. project = u'os-api-ref' copyright = u'2016, The contributors' # 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 # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # -- 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' # html_static_path = ['static'] # Output file base name for HTML help builder. htmlhelp_basename = '%sdoc' % project # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass # [howto/manual]). latex_documents = [ ('index', '%s.tex' % project, u'%s Documentation' % project, u'OpenStack Foundation', 'manual'), ] # Example configuration for intersphinx: refer to the Python standard library. #intersphinx_mapping = {'http://docs.python.org/': None} os-api-ref-0.3.0/doc/source/contributing.rst000066400000000000000000000000771272425777700210120ustar00rootroot00000000000000 Contributing ============ .. include:: ../../CONTRIBUTING.rst os-api-ref-0.3.0/doc/source/index.rst000066400000000000000000000010051272425777700174020ustar00rootroot00000000000000.. os-api-ref documentation master file, created by sphinx-quickstart on Tue Jul 9 22:26:36 2013. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to os-api-ref's documentation! ======================================================== .. include:: readme.rst .. include:: installation.rst .. include:: usage.rst .. include:: contributing.rst Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` os-api-ref-0.3.0/doc/source/installation.rst000066400000000000000000000002721272425777700210010ustar00rootroot00000000000000Installation ============ At the command line:: $ pip install os-api-ref Or, if you have virtualenvwrapper installed:: $ mkvirtualenv os-api-ref $ pip install os-api-ref os-api-ref-0.3.0/doc/source/readme.rst000066400000000000000000000000361272425777700175330ustar00rootroot00000000000000.. include:: ../../README.rst os-api-ref-0.3.0/doc/source/usage.rst000066400000000000000000000167721272425777700174200ustar00rootroot00000000000000Usage ===== ``os-api-ref`` is designed to be used inside of a sphinx tree that is devoted solely to the documentation of the API. Modify your ``source/conf.py`` file to include ``os_api_ref`` in the list of sphinx extensions. This extension assumes you are also using ``oslosphinx`` for some of the styling, and may not fully work if you are not. .. code-block:: python # 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', 'oslosphinx', ] Stanzas ======= rest_method ----------- The ``rest_method`` stanza is a way to declare that a section is about a particular REST method. It takes the form of: .. code-block:: rst .. rest_method:: ``METHODNAME`` should be one of the commonly used REST methods or HTTP verbs. This stanza should be the first element in a ``section`` that has some descriptive title about the method. An example from the Nova documentation is: .. code-block:: rst List Servers ============ .. rest_method:: GET /v2.1/{tenant_id}/servers Lists IDs, names, and links for all servers. Servers contain a status attribute that indicates the current server state. You can filter on the server status when you complete a list servers request. The server status is returned in the response body. The possible server status values are: ... This is going to do a slightly unexpected transform where the ``rest_method`` is pivoted up and into the section title to produce an HTML line of the form: . The entire contents of the ``List Servers`` section will then be hidden by default, with a button to open it on demand. rest_parameters --------------- The ``rest_parameters`` stanza is a solution to the problem of tables in ``rst``. A REST API that uses JSON has a large number of structured parameters that include type, location (i.e. is this in the query, the header, the path, the body), whether or not this parameter is required, as well as the desire to provide a long description about each parameter. And, assuming some consistent modeling, that parameter will show up in multiple calls. A ``server_id`` used in the path is always going to have the same meaning. It is natural to want to display this data in a tabular way to show all these dimensions. However, tables in ``rst`` are quite cumbersome, and repeating the same data over and over again is error prone. The ``rest_parameters`` stanza solves this by having the inline markup be a yaml list of ``name: value`` pairs. ``name`` is the name of the parameter. ``value`` is the key to lookup the rest of the details for this parameter in a parameters file. In each method, there should be one ``rest_parameters`` stanza for the request, and another ``rest_parameters`` stanza for the response. .. code-block:: rst .. rest_parameters:: parameters.yaml - tenant_id: tenant_id - changes-since: changes-since - image: image_query - flavor: flavor_query - name: server_name_query - status: server_status_query - host: host_query - limit: limit - marker: marker And corresponding entries in ``parameters.yaml``: .. code-block:: yaml tenant_id: description: | The UUID of the tenant in a multi-tenancy cloud. in: path required: true type: string ... changes-since: description: | Filters the response by a date and time when the image last changed status. Use this query parameter to check for changes since a previous request rather than re-downloading and re-parsing the full status at each polling interval. If data has changed, the call returns only the items changed since the ``changes-since`` time. If data has not changed since the ``changes-since`` time, the call returns an empty list.\nTo enable you to keep track of changes, this filter also displays images that were deleted if the ``changes-since`` value specifies a date in the last 30 days. Items deleted more than 30 days ago might be returned, but it is not guaranteed. The date and time stamp format is `ISO 8601 `_: :: CCYY-MM-DDThh:mm:ss±hh:mm The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC. For example, ``2015-08-27T09:49:58-05:00``. If you omit the time zone, the UTC time zone is assumed. in: query required: false type: string server_status_query: description: | Filters the response by a server status, as a string. For example, ``ACTIVE``. in: query required: false type: string Every ``rest_parameters`` stanza specifies the lookup file it will use. This gives you the freedom to decide how you would like to split up your parameters, ranging from a single global file, to a dedicated file for every stanza, or anywhere in between. parameters file format ---------------------- The parameters file is inspired by the OpenAPI (aka: Swagger) specification. The OpenAPI specification provides a property object which categorizes the parameters by type and describes how the parameter is used. The following fields exist for every entry: in where this parameter exists. One of ``header``, ``path``, ``query``, ``body``. description a free form description of the parameter. This can be multiline (if using the | or > tags in yaml), and supports ``rst`` format syntax. required whether this parameter is required or not. If ``required: false`` the parameter name will be rendered with an (Optional) keyword next to it type the javascript/json type of the field. one of ``boolean``, ``int``, ``float``, ``string``, ``array``, ``object``. min_version the microversion that this parameter was introduced at. Will render a *new in $version* stanza in the html output. max_version the last version that includes this parameter. Will render a *Deprecated in $version* stanza in the html output. rest_expand_all --------------- The ``rest_expand_all`` stanza is used to place a control in the document that will be a global Show / Hide for all sections. There are times when this is extremely nice to have. Including Sample Files ====================== To refer to a sample file in a ``rst`` file, use the ``rst`` directive, ``literalinclude``. Typically, the content sent or received is of type JSON, so the language role is set to javascript. The example immediately follows the parameter listing in the ``rst`` file. An example of an included Nova response sample file: .. code-block:: rst .. literalinclude:: ../../doc/api_samples/os-evacuate/server-evacuate-resp.json :language: javascript Runtime Warnings ================ The extension tries to help when it can by pointing out that something isn't matching up correctly. The following warnings are generated when issues are found: * parameters file is not found * parameters file is not valid yaml, i.e. missing colon after the name * a lookup value in the ``rst`` file is not found in the parameters file * the parameters file is not sorted as outlined in the rules below The sorting rules for parameters file is that first elements should be sorted by ``in``, going from earliest to latest processed. #. header #. path #. query #. body After that, the parameters should be sorted by name, lower case alpha numerically. The sort enforcement is because in large parameters files it helps prevent unintended duplicates. os-api-ref-0.3.0/os_api_ref/000077500000000000000000000000001272425777700156065ustar00rootroot00000000000000os-api-ref-0.3.0/os_api_ref/__init__.py000066400000000000000000000521011272425777700177160ustar00rootroot00000000000000# -*- 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. from collections import OrderedDict import os from docutils import nodes from docutils.parsers.rst.directives.tables import Table from docutils.statemachine import ViewList import pbr.version from sphinx.util.compat import Directive from sphinx.util.osutil import copyfile import yaml __version__ = pbr.version.VersionInfo( 'os_api_ref').version_string() """This provides a sphinx extension able to create the HTML needed for the api-ref website. It contains 2 new stanzas. .. rest_method:: GET /foo/bar Which is designed to be used as the first stanza in a new section to state that section is about that REST method. During processing the rest stanza will be reparented to be before the section in question, and used as a show/hide selector for it's details. .. rest_parameters:: file.yaml - name1: name_in_file1 - name2: name_in_file2 - name3: name_in_file3 Which is designed to build structured tables for either response or request parameters. The stanza takes a value which is a file to lookup details about the parameters in question. The contents of the stanza are a yaml list of key / value pairs. The key is the name of the parameter to be shown in the table. The value is the key in the file.yaml where all other metadata about the parameter will be extracted. This allows for reusing parameter definitions widely in API definitions, but still providing for control in both naming and ordering of parameters at every declaration. """ def ordered_load(stream, Loader=yaml.Loader, object_pairs_hook=OrderedDict): """Load yaml as an ordered dict This allows us to inspect the order of the file on disk to make sure it was correct by our rules. """ class OrderedLoader(Loader): pass def construct_mapping(loader, node): loader.flatten_mapping(node) return object_pairs_hook(loader.construct_pairs(node)) OrderedLoader.add_constructor( yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, construct_mapping) # for parameters.yaml we treat numbers (especially version # numbers) as strings. So that microversion specification of 2.20 # and 2.2 don't get confused. OrderedLoader.add_constructor( u'tag:yaml.org,2002:float', yaml.constructor.SafeConstructor.construct_yaml_str) return yaml.load(stream, OrderedLoader) class rest_method(nodes.Part, nodes.Element): """Node for rest_method stanza Because we need to insert very specific HTML at the final stage of processing, the rest_method stanza needs a custom node type. This lets us accumulate the relevant data into this node, during parsing, but not turn it into known sphinx types (lists, tables, sections). Then, during the final build phase we transform directly to the html that we want. NOTE: this means we error trying to build latex or man pages for these stanza types right now. This is all fixable if we add an output formatter for this node type, but it's not yet a priority. Contributions welcomed. """ pass class rest_expand_all(nodes.Part, nodes.Element): """A node placeholder for the expand all button. This is a node that we can insert into the doctree which on final render can be converted to the custom HTML we need for the expand all button. It is automatically inserted at the top of the page for API ref documents. """ pass class RestExpandAllDirective(Directive): # This tells sphinx that the directive will need to generate # content during the final build phase. has_content = True def run(self): app = self.state.document.settings.env.app node = rest_expand_all() max_ver = app.config.os_api_ref_max_microversion min_ver = app.config.os_api_ref_min_microversion node['major'] = None try: if max_ver.split('.')[0] == min_ver.split('.')[0]: node['max_ver'] = int(max_ver.split('.')[1]) node['min_ver'] = int(min_ver.split('.')[1]) node['major'] = int(max_ver.split('.')[0]) except ValueError: # TODO(sdague): warn that we're ignoring this all pass except IndexError: pass return [node] class RestMethodDirective(Directive): # this enables content in the directive has_content = True @staticmethod def find_param(content, name): for line in content: if ("%s: " % name) in line: _, value = line.split(': ') return value.rstrip().lstrip() return None def run(self): lineno = self.state_machine.abs_line_number() target = nodes.target() section = nodes.section(classes=["detail-control"]) # env = self.state.document.settings.env # env.app.info("Parent %s" % self.state.parent.attributes) node = rest_method() # TODO(sdague): this is a super simplistic parser, should be # more robust. method, sep, url = self.content[0].partition(' ') node['min_version'] = self.find_param(self.content, 'min_version') node['max_version'] = self.find_param(self.content, 'max_version') node['method'] = method node['url'] = url node['target'] = self.state.parent.attributes['ids'][0] node['css_classes'] = "" if node['min_version']: node['css_classes'] += "rp_min_ver_%s " % ( str(node['min_version']).replace('.', '_')) if node['max_version']: node['css_classes'] += "rp_max_ver_%s " % ( str(node['max_version']).replace('.', '_')) # We need to build a temporary target that we can replace # later in the processing to get the TOC to resolve correctly. temp_target = "%s-selector" % node['target'] target = nodes.target(ids=[temp_target]) self.state.add_target(temp_target, '', target, lineno) section += node return [target, section] # cache for file -> yaml so we only do the load and check of a yaml # file once during a sphinx processing run. YAML_CACHE = {} class RestParametersDirective(Table): headers = ["Name", "In", "Type", "Description"] def _load_param_file(self, fpath): global YAML_CACHE if fpath in YAML_CACHE: return YAML_CACHE[fpath] # self.app.info("Fpath: %s" % fpath) try: with open(fpath, 'r') as stream: lookup = ordered_load(stream) self._check_yaml_sorting(fpath, lookup) except IOError: self.env.warn( self.env.docname, "Parameters file %s not found" % fpath) return except yaml.YAMLError as exc: self.app.warn(exc) raise YAML_CACHE[fpath] = lookup return lookup def _check_yaml_sorting(self, fpath, yaml_data): """check yaml sorting Assuming we got an ordered dict, we iterate through it basically doing a gnome sort test (https://en.wikipedia.org/wiki/Gnome_sort) and ensure the item we are looking at is > the last item we saw. This is done at the section level first, so we're grouped, then alphabetically by lower case name within a section. Every time there is a mismatch we raise an warn message. """ sections = {"header": 1, "path": 2, "query": 3, "body": 4} last = None for key, value in yaml_data.items(): # use of an invalid 'in' value if value['in'] not in sections: self.app.warn( "``%s`` is not a valid value for 'in' (must be one of: %s)" ". (see ``%s``)" % ( value['in'], ", ".join(sorted(sections.keys())), key) ) continue if last is None: last = (key, value) continue # ensure that sections only go up current_section = value['in'] last_section = last[1]['in'] if sections[current_section] < sections[last_section]: self.app.warn( "Section out of order. All parameters in section ``%s`` " "should be after section ``%s``. (see ``%s``)" % ( last_section, current_section, last[0])) if (sections[value['in']] == sections[last[1]['in']] and key.lower() < last[0].lower()): self.app.warn( "Parameters out of order ``%s`` should be after ``%s``" % ( last[0], key)) last = (key, value) def yaml_from_file(self, fpath): """Collect Parameter stanzas from inline + file. This allows use to reference an external file for the actual parameter definitions. """ lookup = self._load_param_file(fpath) content = "\n".join(self.content) parsed = yaml.load(content) # self.app.info("Params loaded is %s" % parsed) # self.app.info("Lookup table looks like %s" % lookup) new_content = list() for paramlist in parsed: for name, ref in paramlist.items(): if ref in lookup: new_content.append((name, lookup[ref])) else: # TODO(sdague): this provides a kind of confusing # error message because env.warn isn't meant to be # used this way, however it does provide a way to # track down where the parameters list is that is # wrong. So it's good enough for now. self.env.warn( "%s:%s " % ( self.state_machine.node.source, self.state_machine.node.line), ("No field definition for ``%s`` found in ``%s``. " " Skipping." % (ref, fpath))) # self.app.info("New content %s" % new_content) self.yaml = new_content def run(self): self.env = self.state.document.settings.env self.app = self.env.app # Make sure we have some content, which should be yaml that # defines some parameters. if not self.content: error = self.state_machine.reporter.error( 'No parameters defined', nodes.literal_block(self.block_text, self.block_text), line=self.lineno) return [error] if not len(self.arguments) >= 1: error = self.state_machine.reporter.error( 'No reference file defined', nodes.literal_block(self.block_text, self.block_text), line=self.lineno) return [error] # NOTE(sdague): it's important that we pop the arg otherwise # we end up putting the filename as the table caption. rel_fpath, fpath = self.env.relfn2path(self.arguments.pop()) self.yaml_file = fpath self.yaml_from_file(self.yaml_file) self.max_cols = len(self.headers) # TODO(sdague): it would be good to dynamically set column # widths (or basically make the colwidth thing go away # entirely) self.options['widths'] = (20, 10, 10, 60) self.col_widths = self.get_column_widths(self.max_cols) # Actually convert the yaml title, messages = self.make_title() # self.app.info("Title %s, messages %s" % (title, messages)) table_node = self.build_table() self.add_name(table_node) if title: table_node.insert(0, title) return [table_node] + messages def get_rows(self, table_data): rows = [] groups = [] trow = nodes.row() entry = nodes.entry() para = nodes.paragraph(text=unicode(table_data)) entry += para trow += entry rows.append(trow) return rows, groups # Add a column for a field. In order to have the RST inside # these fields get rendered, we need to use the # ViewList. Note, ViewList expects a list of lines, so chunk # up our content as a list to make it happy. def add_col(self, value): entry = nodes.entry() result = ViewList(value.split('\n')) self.state.nested_parse(result, 0, entry) return entry def show_no_yaml_error(self): trow = nodes.row(classes=["no_yaml"]) trow += self.add_col("No yaml found %s" % self.yaml_file) trow += self.add_col("") trow += self.add_col("") trow += self.add_col("") return trow def collect_rows(self): rows = [] groups = [] try: # self.app.info("Parsed content is: %s" % self.yaml) for key, values in self.yaml: min_version = values.get('min_version', '') max_version = values.get('max_version', '') desc = values.get('description', '') classes = [] if min_version: desc += ("\n\n**New in version %s**\n" % min_version) min_ver_css_name = ("rp_min_ver_" + str(min_version).replace('.', '_')) classes.append(min_ver_css_name) if max_version: desc += ("\n\n**Deprecated in version %s**\n" % max_version) max_ver_css_name = ("rp_max_ver_" + str(max_version).replace('.', '_')) classes.append(max_ver_css_name) trow = nodes.row(classes=classes) name = key if values.get('required', False) is False: name += " (Optional)" trow += self.add_col(name) trow += self.add_col(values.get('in')) trow += self.add_col(values.get('type')) trow += self.add_col(desc) rows.append(trow) except AttributeError as exc: if 'key' in locals(): self.app.warn("Failure on key: %s, values: %s. %s" % (key, values, exc)) else: rows.append(self.show_no_yaml_error()) return rows, groups def build_table(self): table = nodes.table() tgroup = nodes.tgroup(cols=len(self.headers)) table += tgroup # TODO(sdague): it would be really nice to figure out how not # to have this stanza, it kind of messes up all of the table # formatting because it doesn't let tables just be the right # size. tgroup.extend( nodes.colspec(colwidth=col_width, colname='c' + str(idx)) for idx, col_width in enumerate(self.col_widths) ) thead = nodes.thead() tgroup += thead row_node = nodes.row() thead += row_node row_node.extend(nodes.entry(h, nodes.paragraph(text=h)) for h in self.headers) tbody = nodes.tbody() tgroup += tbody rows, groups = self.collect_rows() tbody.extend(rows) table.extend(groups) return table def rest_method_html(self, node): tmpl = """
%(method)s
%(url)s
%(desc)s
""" node['url'] = node['url'].replace( '{', '{') node['url'] = node['url'].replace( '}', '}') self.body.append(tmpl % node) raise nodes.SkipNode def rest_expand_all_html(self, node): tmpl = """
%(extra_js)s
%(selector)s
""" if node['major']: selector = """
\n""" for x in range(node['min_ver'], node['max_ver'] + 1): selector += ('\n' % (node['major'], x)) selector += "
" node['selector'] = selector node['extra_js'] = ("") % ( node['max_ver'], node['min_ver']) else: node['selector'] = "" node['extra_js'] = "" self.body.append(tmpl % node) raise nodes.SkipNode def resolve_rest_references(app, doctree): for node in doctree.traverse(): if isinstance(node, rest_method): rest_node = node rest_method_section = node.parent rest_section = rest_method_section.parent gp = rest_section.parent # Added required classes to the top section rest_section.attributes['classes'].append('api-detail') rest_section.attributes['classes'].append('collapse') # Pop the title off the collapsed section title = rest_section.children.pop(0) rest_node['desc'] = title.children[0] # In order to get the links in the sidebar to be right, we # have to do some id flipping here late in the game. The # rest_method_section has basically had a dummy id up # until this point just to keep it from colliding with # it's parent. rest_section.attributes['ids'][0] = ( "%s-detail" % rest_section.attributes['ids'][0]) rest_method_section.attributes['ids'][0] = rest_node['target'] # Pop the overall section into it's grand parent, # right before where the current parent lives idx = gp.children.index(rest_section) rest_section.remove(rest_method_section) gp.insert(idx, rest_method_section) def copy_assets(app, exception): assets = ('bootstrap.min.css', 'api-site.css', 'bootstrap.min.js', 'api-site.js', 'glyphicons-halflings-regular.ttf', 'glyphicons-halflings-regular.woff') if app.builder.name != 'html' or exception: return app.info('Copying assets: %s' % ', '.join(assets)) for asset in assets: dest = os.path.join(app.builder.outdir, '_static', asset) source = os.path.abspath(os.path.dirname(__file__)) copyfile(os.path.join(source, 'assets', asset), dest) def add_assets(app): app.add_stylesheet('bootstrap.min.css') app.add_stylesheet('api-site.css') app.add_javascript('bootstrap.min.js') app.add_javascript('api-site.js') def setup(app): # Add some config options around microversions app.add_config_value('os_api_ref_max_microversion', '', 'env') app.add_config_value('os_api_ref_min_microversion', '', 'env') # TODO(sdague): if someone wants to support latex/pdf, or man page # generation using these stanzas, here is where you'd need to # specify content specific renderers. app.add_node(rest_method, html=(rest_method_html, None)) app.add_node(rest_expand_all, html=(rest_expand_all_html, None)) # This specifies all our directives that we're adding app.add_directive('rest_parameters', RestParametersDirective) app.add_directive('rest_method', RestMethodDirective) app.add_directive('rest_expand_all', RestExpandAllDirective) # The doctree-read hook is used do the slightly crazy doc # transformation that we do to get the rest_method document # structure. app.connect('doctree-read', resolve_rest_references) # Add all the static assets to our build during the early stage of building app.connect('builder-inited', add_assets) # This copies all the assets (css, js, fonts) over to the build # _static directory during final build. app.connect('build-finished', copy_assets) return {'version': __version__} os-api-ref-0.3.0/os_api_ref/assets/000077500000000000000000000000001272425777700171105ustar00rootroot00000000000000os-api-ref-0.3.0/os_api_ref/assets/api-site.css000066400000000000000000000051551272425777700213430ustar00rootroot00000000000000tt.literal { padding: 2px 4px; font-size: 90%; color: #c7254e; white-space: nowrap; background-color: #f9f2f4; border-radius: 4px; } /* bootstrap users blockquote for pull quotes, so they are much larger, we need them smaller */ blockquote { font-size: 1em; } pre { display: block; padding: 9.5px; margin: 0 0 10px; font-size: 13px; line-height: 1.428571429; color: #333; word-break: break-all; word-wrap: break-word; background-color: #f5f5f5; border: 1px solid #ccc; border-radius: 4px; } tbody>tr:nth-child(odd)>td, tbody>tr:nth-child(odd)>th { background-color: #f9f9f9; } table>thead>tr>th, table>tbody>tr>th, table>tfoot>tr>th, table>thead>tr>td, table>tbody>tr>td, table>tfoot>tr>td { padding: 8px; line-height: 1.428571429; vertical-align: top; border-top: 1px solid #ddd; } td>p { margin: 0 0 0.5em; } div.document { width: 80% !important; } @media (max-width: 1200px) { div.document { width: 960px !important; } } .operation-grp { padding-top: 0.5em; padding-bottom: 1em; } /* Ensure the method buttons and their links don't split lines when the page is narrower */ .operation { /* this moves the link icon into the gutter */ margin-left: -1.25em; margin-right: 1.25em; white-space: nowrap; } /* These make the links only show up on hover */ a.operation-anchor { visibility: hidden; } .operation-grp:hover a.operation-anchor { visibility: visible; } /* All tables for requests should be full width */ .api-detail table.docutils { width: 100%; } .versionmodified { font-weight: bold; } .label-POST { background-color: #5cb85c; } .label-POST[href]:hover, .label-POST[href]:focus { background-color: #449d44; } .label-GET, .label-HEAD { background-color: #5bc0de; } .label-GET[href]:hover, .label-GET[href]:focus, .label-HEAD[href]:hover, .label-HEAD[href]:focus { background-color: #31b0d5; } .label-PUT, .label-PATCH { background-color: #f0ad4e; } .label-PUT[href]:hover, .label-PUT[href]:focus, .label-PATCH[href]:hover, .label-PATCH[href]:focus { background-color: #ec971f; } .label-DELETE { background-color: #d9534f; } .label-DELETE[href]:hover, .label-DELETE[href]:focus { background-color: #c9302c; } span.path_parameter { font-family: monospace; padding: 2px 4px; font-size: 90%; color: #c7254e; white-space: nowrap; background-color: #f9f2f4; border-radius: 4px; } /* for microversion selector */ .mv_selector { font-size: 0.8em; padding: 0.3em; } .mv_selector.active { color: #fff; background-color: #31b0d5; border-color: #269abc; }os-api-ref-0.3.0/os_api_ref/assets/api-site.js000066400000000000000000000143311272425777700211630ustar00rootroot00000000000000var os_min_mv = 1; var os_max_mv = 1; (function() { // the list of expanded element ids var expanded = []; // whether we should sync expand changes with the location // url. We need to make this false during large scale // operations because we're using the history API, which is // expensive. So a bulk expand turns this off, expands // everything, turns it back on, then does a history sync. var should_sync = true; $(document).ready(function() { // Change the text on the expando buttons when // appropriate. This also add or removes them to the list of // expanded sections, and then syncs that list to the history // after such a change. $('.api-detail') .on('hide.bs.collapse', function(e) { processButton(this, 'detail'); var index = expanded.indexOf(this.id); if (index > -1) { expanded.splice(index, 1); } sync_expanded(); }) .on('show.bs.collapse', function(e) { processButton(this, 'close'); expanded.push(this.id); sync_expanded(); }); // Expand the world. Wires up the expand all button, it turns // off tye sync while it is running to save the costs with the // history API. var expandAllActive = true; $('#expand-all').click(function () { should_sync = false; if (expandAllActive) { expandAllActive = false; $('.api-detail').collapse('show'); $('#expand-all').attr('data-toggle', ''); $(this).text('Hide All'); } else { expandAllActive = true; $('.api-detail').collapse('hide'); $('#expand-all').attr('data-toggle', 'collapse'); $(this).text('Show All'); } should_sync = true; sync_expanded(); }); // if there is an expanded parameter passed in a url, we run // through and expand all the appropriate things. if (window.location.search.substring(1).indexOf("expanded") > -1) { should_sync = false; var parts = window.location.search.substring(1).split('&'); for (var i = 0; i < parts.length; i++) { var keyval = parts[i].split('='); if (keyval[0] == "expanded" && keyval[1]) { var expanded_ids = keyval[1].split(','); for (var j = 0; j < expanded_ids.length; j++) { $('#' + expanded_ids[j]).collapse('show'); } } } should_sync = true; // This is needed because the hash *might* be inside a // collapsed section. // // NOTE(sdague): this doesn't quite seem to work while // we're changing the rest of the document. $(document.body).scrollTop($(window.location.hash).offset().top); } // Wire up microversion selector $('.mv_selector').on('click', function(e) { var version = e.currentTarget.innerHTML; // flip what is active $(this).addClass('active').siblings().removeClass('active'); if (version == "All") { reset_microversion(); } else { set_microversion(version); } }); }); /** * Helper function for setting the text, styles for expandos */ function processButton(button, text) { $('#' + $(button).attr('id') + '-btn').text(text) .toggleClass('btn-info') .toggleClass('btn-default'); } // Take the expanded array and push it into history. Because // sphinx is building css appropriate ids, they should not have // any special characters we need to encode. So we can simply join // them into a comma separated list. function sync_expanded() { if (should_sync) { var url = UpdateQueryString('expanded', expanded.join(',')); history.pushState('', 'new expand', url); } } // Generically update the query string for a url. Credit to // http://stackoverflow.com/questions/5999118/add-or-update-query-string-parameter // for making this properly generic. function UpdateQueryString(key, value, url) { if (!url) url = window.location.href; var re = new RegExp("([?&])" + key + "=.*?(&|#|$)(.*)", "gi"), hash; if (re.test(url)) { if (typeof value !== 'undefined' && value !== null) return url.replace(re, '$1' + key + "=" + value + '$2$3'); else { hash = url.split('#'); url = hash[0].replace(re, '$1$3').replace(/(&|\?)$/, ''); if (typeof hash[1] !== 'undefined' && hash[1] !== null) url += '#' + hash[1]; return url; } } else { if (typeof value !== 'undefined' && value !== null) { var separator = url.indexOf('?') !== -1 ? '&' : '?'; hash = url.split('#'); url = hash[0] + separator + key + '=' + value; if (typeof hash[1] !== 'undefined' && hash[1] !== null) url += '#' + hash[1]; return url; } else return url; } } // Set the Y value of the microversion to turn on / off visibility // of components. function set_microversion(number) { var major = number.split(".")[0]; var micro = number.split(".")[1]; for (var i = os_min_mv; i <= os_max_mv; i++) { var max_class = ".rp_max_ver_" + major + "_" + i; var min_class = ".rp_min_ver_" + major + "_" + i; if (i < micro) { $(max_class).hide(400); $(min_class).show(400); } else if (i >= micro) { $(min_class).hide(400); $(max_class).show(400); } } } function reset_microversion() { $('[class^=rp_min_ver]').show(400); $('[class^=rp_max_ver]').show(400); } })(); os-api-ref-0.3.0/os_api_ref/tests/000077500000000000000000000000001272425777700167505ustar00rootroot00000000000000os-api-ref-0.3.0/os_api_ref/tests/__init__.py000066400000000000000000000000001272425777700210470ustar00rootroot00000000000000os-api-ref-0.3.0/os_api_ref/tests/base.py000066400000000000000000000062241272425777700202400ustar00rootroot00000000000000# -*- coding: utf-8 -*- # Copyright 2010-2011 OpenStack Foundation # Copyright (c) 2013 Hewlett-Packard Development Company, L.P. # # 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 os import fixtures import testtools def example_dir(name=""): return os.path.join(os.path.dirname(__file__), 'examples', name) _TRUE_VALUES = ('True', 'true', '1', 'yes') class OutputStreamCapture(fixtures.Fixture): """Capture output streams during tests. This fixture captures errant printing to stderr / stdout during the tests and lets us see those streams at the end of the test runs instead. Useful to see what was happening during failed tests. """ def setUp(self): super(OutputStreamCapture, self).setUp() if os.environ.get('OS_STDOUT_CAPTURE') in _TRUE_VALUES: self.out = self.useFixture(fixtures.StringStream('stdout')) self.useFixture( fixtures.MonkeyPatch('sys.stdout', self.out.stream)) if os.environ.get('OS_STDERR_CAPTURE') in _TRUE_VALUES: self.err = self.useFixture(fixtures.StringStream('stderr')) self.useFixture( fixtures.MonkeyPatch('sys.stderr', self.err.stream)) @property def stderr(self): return self.err._details["stderr"].as_text() @property def stdout(self): return self.out._details["stdout"].as_text() class Timeout(fixtures.Fixture): """Setup per test timeouts. In order to avoid test deadlocks we support setting up a test timeout parameter read from the environment. In almost all cases where the timeout is reached this means a deadlock. A class level TIMEOUT_SCALING_FACTOR also exists, which allows extremely long tests to specify they need more time. """ def __init__(self, timeout, scaling=1): super(Timeout, self).__init__() try: self.test_timeout = int(timeout) except ValueError: # If timeout value is invalid do not set a timeout. self.test_timeout = 0 if scaling >= 1: self.test_timeout *= scaling else: raise ValueError('scaling value must be >= 1') def setUp(self): super(Timeout, self).setUp() if self.test_timeout > 0: self.useFixture(fixtures.Timeout(self.test_timeout, gentle=True)) class TestCase(testtools.TestCase): """Test case base class for all unit tests.""" def setUp(self): """Run before each test method to initialize test environment.""" super(TestCase, self).setUp() self.useFixture(Timeout( os.environ.get('OS_TEST_TIMEOUT', 0))) self.useFixture(OutputStreamCapture()) os-api-ref-0.3.0/os_api_ref/tests/examples/000077500000000000000000000000001272425777700205665ustar00rootroot00000000000000os-api-ref-0.3.0/os_api_ref/tests/examples/basic/000077500000000000000000000000001272425777700216475ustar00rootroot00000000000000os-api-ref-0.3.0/os_api_ref/tests/examples/basic/conf.py000066400000000000000000000017021272425777700231460ustar00rootroot00000000000000# -*- 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. # -- 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. extensions = [ 'os_api_ref', 'oslosphinx', ] # The suffix of source filenames. source_suffix = '.rst' # The master toctree document. master_doc = 'index' os-api-ref-0.3.0/os_api_ref/tests/examples/basic/index.rst000066400000000000000000000002621272425777700235100ustar00rootroot00000000000000.. rest_expand_all:: I am text, hear me roar! ============== List Servers ============== .. rest_method:: GET /servers .. rest_parameters:: parameters.yaml - name: name os-api-ref-0.3.0/os_api_ref/tests/examples/basic/parameters.yaml000066400000000000000000000001311272425777700246710ustar00rootroot00000000000000name: in: body required: true type: string description: | The name of things os-api-ref-0.3.0/os_api_ref/tests/examples/microversions/000077500000000000000000000000001272425777700234705ustar00rootroot00000000000000os-api-ref-0.3.0/os_api_ref/tests/examples/microversions/conf.py000066400000000000000000000020141272425777700247640ustar00rootroot00000000000000# -*- 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. # -- 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. extensions = [ 'os_api_ref', 'oslosphinx', ] # The suffix of source filenames. source_suffix = '.rst' # The master toctree document. master_doc = 'index' os_api_ref_min_microversion = '2.1' os_api_ref_max_microversion = '2.30' os-api-ref-0.3.0/os_api_ref/tests/examples/microversions/index.rst000066400000000000000000000005001272425777700253240ustar00rootroot00000000000000.. rest_expand_all:: I am text, hear me roar! ============== List Servers ============== .. rest_method:: GET /servers .. rest_parameters:: parameters.yaml - name: name - name2: name2 - name3: name3 =========== List Tags =========== .. rest_method:: GET /tags min_version: 2.17 max_version: 2.19 os-api-ref-0.3.0/os_api_ref/tests/examples/microversions/parameters.yaml000066400000000000000000000004641272425777700265230ustar00rootroot00000000000000name: in: body required: true type: string description: | The name of things name2: in: body required: true type: string description: | The name of things min_version: 2.11 name3: in: body required: true type: string description: | The name of things max_version: 2.20os-api-ref-0.3.0/os_api_ref/tests/examples/warnings/000077500000000000000000000000001272425777700224165ustar00rootroot00000000000000os-api-ref-0.3.0/os_api_ref/tests/examples/warnings/conf.py000066400000000000000000000017021272425777700237150ustar00rootroot00000000000000# -*- 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. # -- 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. extensions = [ 'os_api_ref', 'oslosphinx', ] # The suffix of source filenames. source_suffix = '.rst' # The master toctree document. master_doc = 'index' os-api-ref-0.3.0/os_api_ref/tests/examples/warnings/index.rst000066400000000000000000000003371272425777700242620ustar00rootroot00000000000000.. rest_expand_all:: I am text, hear me roar! ============== List Servers ============== .. rest_method:: GET /servers .. rest_parameters:: parameters.yaml - name: name - name: lookup_key_name - name: name_1 os-api-ref-0.3.0/os_api_ref/tests/examples/warnings/parameters.yaml000066400000000000000000000004601272425777700254450ustar00rootroot00000000000000# These are out of order, this should be a warning. name2: in: body required: false type: string description: | foo name: in: body required: true type: string description: | The name of things name_1: description: | name_1 is missing type field. in: body required: true os-api-ref-0.3.0/os_api_ref/tests/test_basic_example.py000066400000000000000000000063231272425777700231610ustar00rootroot00000000000000# -*- 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. """ test_os_api_ref ---------------------------------- Tests for `os_api_ref` module. """ from bs4 import BeautifulSoup from sphinx_testing import with_app from os_api_ref.tests import base class TestBasicExample(base.TestCase): """Test basic rendering. This can be used to test that basic rendering works for these examples, so if someone breaks something we know. """ @with_app(buildername='html', srcdir=base.example_dir('basic'), copy_srcdir_to_tmpdir=True) def setUp(self, app, status, warning): super(TestBasicExample, self).setUp() self.app = app self.status = status self.warning = warning self.app.build() self.html = (app.outdir / 'index.html').read_text() self.soup = BeautifulSoup(self.html, 'html.parser') self.content = str(self.soup) def test_expand_all(self): """Do we get an expand all button like we expect.""" content = str(self.soup.find(id='expand-all')) example_button = ('') self.assertEqual( example_button, content) def test_rest_method(self): """Do we get a REST method call block""" # TODO(sdague): it probably would make sense to do this as a # whole template instead of parts. content = str(self.soup.find_all(class_='operation-grp')) self.assertIn( '', str(content)) self.assertIn( 'GET', str(content)) self.assertIn( '
/servers
', str(content)) self.assertIn( (''), str(content)) def test_parameters(self): """Do we get some parameters table""" table = """
Name In Type Description
name body string The name of things
""" self.assertIn(table, self.content) os-api-ref-0.3.0/os_api_ref/tests/test_microversions.py000066400000000000000000000130101272425777700232560ustar00rootroot00000000000000# -*- 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. """ test_os_api_ref ---------------------------------- Tests for `os_api_ref` module. """ from bs4 import BeautifulSoup from sphinx_testing import with_app from os_api_ref.tests import base class TestMicroversions(base.TestCase): """Test basic rendering. This can be used to test that basic rendering works for these examples, so if someone breaks something we know. """ @with_app(buildername='html', srcdir=base.example_dir('microversions'), copy_srcdir_to_tmpdir=True) def setUp(self, app, status, warning): super(TestMicroversions, self).setUp() self.app = app self.app.build() self.status = status.getvalue() self.warning = warning.getvalue() self.html = (app.outdir / 'index.html').read_text() self.soup = BeautifulSoup(self.html, 'html.parser') self.content = str(self.soup) def test_rest_method(self): """Test that min / max mv css class attributes are set""" content = self.soup.find_all(class_='rp_min_ver_2_17') self.assertIn( '
', str(content[0])) content = self.soup.find_all(class_='rp_max_ver_2_19') self.assertIn( '
', str(content[0])) def test_parameters_table(self): """Test that min / max mv css class attributes are set in params""" table = """
Name In Type Description
name body string The name of things
name2 body string

The name of things

New in version 2.11
name3 body string

The name of things

Deprecated in version 2.20
""" # noqa self.assertIn(table, self.content) def test_mv_selector(self): button_selectors = \ """
""" self.assertIn(button_selectors, self.content) def test_js_declares(self): self.assertIn("os_max_mv = 30;", self.content) self.assertIn("os_min_mv = 1;", self.content) os-api-ref-0.3.0/os_api_ref/tests/test_os_api_ref.py000066400000000000000000000014141272425777700224670ustar00rootroot00000000000000# -*- 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. """ test_os_api_ref ---------------------------------- Tests for `os_api_ref` module. """ from os_api_ref.tests import base class TestOs_api_ref(base.TestCase): def test_something(self): pass os-api-ref-0.3.0/os_api_ref/tests/test_warnings.py000066400000000000000000000044531272425777700222170ustar00rootroot00000000000000# -*- 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. """ test_os_api_ref ---------------------------------- Tests for `os_api_ref` module. """ from bs4 import BeautifulSoup from sphinx_testing import with_app from os_api_ref.tests import base class TestWarnings(base.TestCase): """Test basic rendering. This can be used to test that basic rendering works for these examples, so if someone breaks something we know. """ @with_app(buildername='html', srcdir=base.example_dir('warnings'), copy_srcdir_to_tmpdir=True) def setUp(self, app, status, warning): super(TestWarnings, self).setUp() self.app = app self.app.build() self.status = status.getvalue() self.warning = warning.getvalue() self.html = (app.outdir / 'index.html').read_text() self.soup = BeautifulSoup(self.html, 'html.parser') self.content = str(self.soup) def test_out_of_order(self): """Do we get an out of order naming warning.""" self.assertIn( ("WARNING: Parameters out of order ``name2`` " "should be after ``name``"), self.warning) def test_missing_lookup_name(self): """Warning when missing lookup key in parameter file.""" self.assertIn( ("WARNING: No field definition for ``lookup_key_name`` found in "), self.warning) def test_missing_field(self): """Warning when missing type field in parameter file.""" self.assertIn( ("WARNING: Failure on key: name, values: " + "OrderedDict([('description'," + " 'name_1 is missing type field.\\n'), ('in', 'body')," + " ('required', True)]). " + "'NoneType' object has no attribute 'split'\n"), self.warning) os-api-ref-0.3.0/requirements.txt000066400000000000000000000003521272425777700167640ustar00rootroot00000000000000# The order of packages is significant, because pip processes them in the order # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. pbr>=1.6 PyYAML>=3.1.0 os-api-ref-0.3.0/setup.cfg000066400000000000000000000022471272425777700153260ustar00rootroot00000000000000[metadata] name = os-api-ref summary = Sphinx Extensions to support API reference sites in OpenStack description-file = README.rst author = OpenStack author-email = openstack-dev@lists.openstack.org home-page = http://www.openstack.org/ classifier = Environment :: OpenStack Intended Audience :: Information Technology Intended Audience :: System Administrators License :: OSI Approved :: Apache Software License Operating System :: POSIX :: Linux Programming Language :: Python Programming Language :: Python :: 2 Programming Language :: Python :: 2.7 Programming Language :: Python :: 3 Programming Language :: Python :: 3.3 Programming Language :: Python :: 3.4 [files] packages = os_api_ref [build_sphinx] source-dir = doc/source build-dir = doc/build all_files = 1 [upload_sphinx] upload-dir = doc/build/html [compile_catalog] directory = os_api_ref/locale domain = os_api_ref [update_catalog] domain = os_api_ref output_dir = os_api_ref/locale input_file = os_api_ref/locale/os_api_ref.pot [extract_messages] keywords = _ gettext ngettext l_ lazy_gettext mapping_file = babel.cfg output_file = os_api_ref/locale/os_api_ref.pot os-api-ref-0.3.0/setup.py000066400000000000000000000017771272425777700152260ustar00rootroot00000000000000# Copyright (c) 2013 Hewlett-Packard Development Company, L.P. # # 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. # THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT import setuptools # In python < 2.7.4, a lazy loading of package `pbr` will break # setuptools if some other modules registered functions in `atexit`. # solution from: http://bugs.python.org/issue15881#msg170215 try: import multiprocessing # noqa except ImportError: pass setuptools.setup( setup_requires=['pbr'], pbr=True) os-api-ref-0.3.0/test-requirements.txt000066400000000000000000000006151272425777700177430ustar00rootroot00000000000000# The order of packages is significant, because pip processes them in the order # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. hacking<0.11,>=0.10.0 coverage>=3.6 python-subunit>=0.0.18 sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2 oslosphinx>=2.5.0 # Apache-2.0 testrepository>=0.0.18 testtools>=1.4.0 sphinx-testing bs4 os-api-ref-0.3.0/tox.ini000066400000000000000000000014061272425777700150140ustar00rootroot00000000000000[tox] minversion = 2.0 envlist = py27,pep8,docs skipsdist = True [testenv] install_command = pip install -U {opts} {packages} deps = -r{toxinidir}/requirements.txt -r{toxinidir}/test-requirements.txt commands = python setup.py test --slowest --no-parallel --testr-args='{posargs}' [testenv:pep8] commands = flake8 {posargs} [testenv:venv] commands = {posargs} [testenv:cover] commands = python setup.py test --coverage --testr-args='{posargs}' [testenv:docs] commands = python setup.py build_sphinx [testenv:debug] commands = oslo_debug_helper {posargs} [flake8] # E123, E125 skipped as they are invalid PEP-8. show-source = True ignore = E123,E125,E129 builtins = _ exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build