diff --git a/.coveragerc b/.coveragerc deleted file mode 100644 index 02b0f84..0000000 --- a/.coveragerc +++ /dev/null @@ -1,7 +0,0 @@ -[run] -branch = True -source = os_api_ref -omit = os_api_ref/openstack/* - -[report] -ignore_errors = True diff --git a/.gitignore b/.gitignore deleted file mode 100644 index e52bb44..0000000 --- a/.gitignore +++ /dev/null @@ -1,55 +0,0 @@ -*.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? diff --git a/.gitreview b/.gitreview deleted file mode 100644 index 76250b0..0000000 --- a/.gitreview +++ /dev/null @@ -1,4 +0,0 @@ -[gerrit] -host=review.openstack.org -port=29418 -project=openstack/os-api-ref.git diff --git a/.mailmap b/.mailmap deleted file mode 100644 index 516ae6f..0000000 --- a/.mailmap +++ /dev/null @@ -1,3 +0,0 @@ -# Format is: -# -# diff --git a/.testr.conf b/.testr.conf deleted file mode 100644 index 6d83b3c..0000000 --- a/.testr.conf +++ /dev/null @@ -1,7 +0,0 @@ -[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 diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 2865cbf..0000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,17 +0,0 @@ -If 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 diff --git a/HACKING.rst b/HACKING.rst deleted file mode 100644 index b1bf86f..0000000 --- a/HACKING.rst +++ /dev/null @@ -1,4 +0,0 @@ -os-api-ref Style Commandments -=============================================== - -Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/ diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 68c771a..0000000 --- a/LICENSE +++ /dev/null @@ -1,176 +0,0 @@ - - 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. - diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index c978a52..0000000 --- a/MANIFEST.in +++ /dev/null @@ -1,6 +0,0 @@ -include AUTHORS -include ChangeLog -exclude .gitignore -exclude .gitreview - -global-exclude *.pyc diff --git a/README b/README new file mode 100644 index 0000000..8fcd2b2 --- /dev/null +++ b/README @@ -0,0 +1,14 @@ +This project is no longer maintained. + +The contents of this repository are still available in the Git +source code management system. To see the contents of this +repository before it reached its end of life, please check out the +previous commit with "git checkout HEAD^1". + +For ongoing work on maintaining OpenStack packages in the Debian +distribution, please see the Debian OpenStack packaging team at +https://wiki.debian.org/OpenStack/. + +For any further questions, please email +openstack-dev@lists.openstack.org or join #openstack-dev on +Freenode. diff --git a/README.rst b/README.rst deleted file mode 100644 index 62a40f2..0000000 --- a/README.rst +++ /dev/null @@ -1,112 +0,0 @@ -======================== -Team and repository tags -======================== - -.. image:: http://governance.openstack.org/badges/os-api-ref.svg - :target: http://governance.openstack.org/reference/tags/index.html - -.. Change things from this point on - -os-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 its strength. This provides tooling -to insert semi-structured data describing request and response -parameters and status or error messages, and turn those into nice tables. - -The project also includes a set of styling (and javascript) that is -expected to layer on top of a Sphinx theme base. This addition -provides a nice set of collapsing sections for REST methods and -javascript controls to expand / collapse all sections. - -Features --------- - -* Sphinx stanza ``rest_method`` describing the method and resource for a REST - API call. Lets authors write simply and also gives readers a clean way to - scan all methods then click a button to get more information about a method. -* Sphinx stanza ``rest_parameters`` used to insert semi-structured data into - the RST files describing the parameters users can send with the request. The - stanza points to a structured YAML file, ``parameters.yaml``. -* Sphinx stanza ``rest_status_code`` used to insert pointers to error or status - codes returned by the service. Points to a structured YAML file, - ``http_codes.yaml``. - -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`` or ``mugsie`` -to discuss or send an email to the openstack-dev@lists.openstack.org list -with [api] in the subject line. - -* Enhance documentation with more examples and best practices -* Testing for the code -* ``max_microversion`` parameter support - so that we automatically - tag parameters that have been removed -* Make a 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), in progress. - -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 --------------- - -**rest_method**: Enter the REST method, such as GET, PUT, POST, DELETE, -followed by the resource (not including an endpoint) for the call. For -example:: - - .. rest_method:: PUT /v2/images/{image_id}/file - -**rest_parameters**: Enter a reference to a ``parameters.yaml`` file and -indicate which parameter you want to document. For example:: - - .. rest_parameters:: images-parameters.yaml - - - Content-type: Content-Type-data - - image_id: image_id-in-path - -Where the ``images-parameters.yaml`` file contains pointers named -``Content-type`` and ``image_id`` and descriptions for each. - -**rest_status_code**: Enter a reference to a ``http-status.yaml`` file and -indicate which errors or status codes you want to document. You can also add -a pointer to more precise descriptions for each code. For example:: - - .. rest_status_code:: success http-codes.yaml - - - 204 - - .. rest_status_code:: error http-codes.yaml - - - 400: informal - - 401 - - 403 - - 404 - - 409 - - 410: image-data-410 - - 413: image-data-413 - - 415: image-data-415 - - 500: informal - - 503: image-data-503 - - -* Free software: Apache license -* Documentation: http://docs.openstack.org/developer/os-api-ref -* Source: http://git.openstack.org/cgit/openstack/os-api-ref diff --git a/RELEASING.rst b/RELEASING.rst deleted file mode 100644 index 65452b9..0000000 --- a/RELEASING.rst +++ /dev/null @@ -1,41 +0,0 @@ -=========== - Releasing -=========== - -This documents the how and when to release ``os-api-ref``. - -When to release -=============== - -Any time there are fixes or additions ready to go, they should be -released. Releases are cheap. If it's been more than a month and there -are changes in master, consider releasing them. - -If the changes are entirely on the CSS / JS cosmetic side, things are -usually pretty safe to release as long as they have been spot checked -against a couple of projects. (The gate does the nova tree -automatically). - -If new warnings are added -------------------------- - -If **new** warnings have been added since the last release, care -should be taken to: - - * Alert the mailing list 2 days before the release about the new - warning coming in (that should give them time to go non enforcing - or fix the issue). - * Ensure that you bump at least the Y in the version number - (X.Y.Z). New warnings are not a Z level release. - -How to release -============== - -Check out ``openstack/releases`` - -Edit ``deliverables/_independent/os-api-ref.yaml`` - -Add a line with the version number desired, the git has of the commit -that should be that release. - -If you have questions ask in ``#openstack-release`` diff --git a/TESTS.rst b/TESTS.rst deleted file mode 100644 index b8029b2..0000000 --- a/TESTS.rst +++ /dev/null @@ -1,14 +0,0 @@ -============================== - 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. diff --git a/babel.cfg b/babel.cfg deleted file mode 100644 index 15cd6cb..0000000 --- a/babel.cfg +++ /dev/null @@ -1,2 +0,0 @@ -[python: **.py] - diff --git a/doc/source/conf.py b/doc/source/conf.py deleted file mode 100755 index c9ed61b..0000000 --- a/doc/source/conf.py +++ /dev/null @@ -1,74 +0,0 @@ -# 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} diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 0021f68..0000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,4 +0,0 @@ - -Contributing -============ -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/http-status.yaml b/doc/source/http-status.yaml deleted file mode 100644 index 3d0928e..0000000 --- a/doc/source/http-status.yaml +++ /dev/null @@ -1,63 +0,0 @@ - 200: - default: | - Request was successful. - image-data-200: | - The service lists the image data in the response body. - 201: - default: | - Request has been fulfilled and new resource created. - 202: - default: | - Request is accepted, but processing may take some time. - 203: - default: | - Returned information is not full set, but a subset. - 204: - default: | - Request fulfilled but service does not return anything. - 300: - default: | - The resource corresponds to more than one representation. - 400: - default: | - Some content in the request was invalid. - 401: - default: | - User must authenticate before making a request. - 403: - default: | - Policy does not allow current user to do this operation. - 404: - default: | - The requested resource could not be found. - 405: - default: | - Method is not valid for this endpoint and resource. - 409: - default: | - This resource has an action in progress that would conflict with this request. - 413: - default: | - This operation cannot be completed. - image-data-413: | - The payload cannot be accepted. Possible causes include: - * The backend storage is full. - * This request added to your existing image data exceeds your total - storage quota for images. - * The image payload submitted with this request exceeds the maximum - allowable image size. - 415: - default: | - The entity of the request is in a format not supported by the requested - resource for the method. - 500: - default: | - Something went wrong with the service which prevents it from fulfilling - the request. - 501: - default: | - The service does not have the functionality required to fulfill this - request. - 503: - default: | - The service cannot handle the request right now. diff --git a/doc/source/index.rst b/doc/source/index.rst deleted file mode 100644 index 61922c5..0000000 --- a/doc/source/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. 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 developer documentation! -============================================== - - -.. toctree:: - :maxdepth: 1 - - installation - usage - contributing - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index 967a6b0..0000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,11 +0,0 @@ -Installation -============ - -At the command line:: - - $ pip install os-api-ref - -Or, if you have virtualenvwrapper installed:: - - $ mkvirtualenv os-api-ref - $ pip install os-api-ref diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index 1e42a6d..0000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,340 +0,0 @@ -Usage -===== - -``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 -``openstackdocstheme`` 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', - ] - - -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_status_code ----------------- - -The ``rest_status_code`` stanza is how you can show what HTTP status codes your -API uses and what they indicate. - -.. code-block:: rst - - .. rest_status_code:: - -This stanza should be the first element after the narrative section of the -method description. - -An example from the Designate documentation is: - -.. code-block:: rst - :emphasize-lines: 11-25 - - Create Zone - =========== - - .. rest_method:: POST /v2/zones - - Create a zone - - Response codes - -------------- - - .. rest_status_code:: success status.yaml - - - 200 - - 100 - - 201 - - - .. rest_status_code:: error status.yaml - - - 405 - - 403 - - 401 - - 400 - - 500 - - 409: duplicate_zone - -And corresponding entries in ``http-status.yaml``: - -.. code-block:: yaml - - 100: - default: | - An unusual code for an API - 200: - default: | - Request was successful. - 201: - default: > - Request has been fulfilled and new resource created. The ``Location`` header - has the URL to the new item. - 400: - default: | - Some content in the request was invalid - zone_data_error: | - Some of the data for the zone in the request is unavailable to the service. - 401: - default: | - User must authenticate before making a request. - 403: - default: | - Policy does not allow current user to do this operation. - 405: - default: | - Method is not valid for this endpoint and resource. - 409: - default: | - This resource has an action in progress that would conflict with this request. - duplicate_zone: | - There is already a zone with this name. - 500: - default: | - Something went wrong with the service which prevents it from fulfilling the request. - -This RST example creates two HTML tables of response codes, one for success and one for -errors. - -status file format ------------------- - -This is a simple yaml file, with a single object of status codes and the -reasons that each would be used. - -Each status code **must** have a default entry in the status yaml file. The default entry is used -in the ``rest_status_code`` stanza when a code is listed with no value or lookup key. - -There may be situations where the reason for a code may be different across -endpoints, or a different message may be appropriate. - -In this case, adding a entry at the same level as the ``default`` and -referencing that in the stanza like so: - -.. code-block:: yaml - - - 409: duplicate_zone - -This will override the default message with the newly defined one. - -You can get a copy of a starter status file from the os-api-ref repository, -by downloading :download:`http-status.yaml `. - -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. diff --git a/os_api_ref/__init__.py b/os_api_ref/__init__.py deleted file mode 100644 index ea83d34..0000000 --- a/os_api_ref/__init__.py +++ /dev/null @@ -1,705 +0,0 @@ -# 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 -import re - -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 - -from os_api_ref.http_codes import http_code -from os_api_ref.http_codes import http_code_html -from os_api_ref.http_codes import HTTPResponseCodeDirective - -__version__ = pbr.version.VersionInfo( - 'os_api_ref').version_string() - -# This is to allow for a graceful swap from oslosphinx to openstackdocstheme -THEME = 'openstackdocstheme' - - -"""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.SafeLoader, 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 - releases = app.config.os_api_ref_release_microversions - 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]) - node['releases'] = releases - 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 - - # Extract the path parameters from the url - env = self.state.document.settings.env - env.path_params = [] - env.path_params = re.findall("{[a-zA-Z][a-zA-Z_0-9]*}", 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] - - lookup = {} - # self.app.info("Fpath: %s" % fpath) - try: - with open(fpath, 'r') as stream: - lookup = ordered_load(stream) - except IOError: - self.app.warn( - "Parameters file %s not found" % fpath, - (self.env.docname, None)) - return - except yaml.YAMLError as exc: - self.app.warn(exc) - raise - - if lookup: - self._check_yaml_sorting(fpath, lookup) - else: - self.app.warn( - "Parameters file is empty %s" % fpath, - (self.env.docname, None)) - return - - 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) - if not lookup: - return - - content = "\n".join(self.content) - parsed = yaml.safe_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: - if not isinstance(paramlist, dict): - self.app.warn( - ("Invalid parameter definition ``%s``. Expected " - "format: ``name: reference``. " - " Skipping." % paramlist), - (self.state_machine.node.source, - self.state_machine.node.line)) - continue - 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 app.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.app.warn( - ("No field definition for ``%s`` found in ``%s``. " - " Skipping." % (ref, fpath)), - (self.state_machine.node.source, - self.state_machine.node.line)) - - # Check for path params in stanza - for i, param in enumerate(self.env.path_params): - if (param.rstrip('}').lstrip('{')) == name: - del self.env.path_params[i] - break - else: - continue - - if len(self.env.path_params) is not 0: - # Warn that path parameters are not set in rest_parameter - # stanza and will not appear in the generated table. - for param in self.env.path_params: - self.app.warn( - ("No path parameter ``%s`` found in rest_parameter" - " stanza.\n" - % param.rstrip('}').lstrip('{')), - (self.state_machine.node.source, - self.state_machine.node.line)) - - # 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) - if isinstance(self.col_widths, tuple): - # In docutils 0.13.1, get_column_widths returns a (widths, - # colwidths) tuple, where widths is a string (i.e. 'auto'). - # See https://sourceforge.net/p/docutils/patches/120/. - self.col_widths = self.col_widths[1] - # 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 -
-
- -
-
""" - - node.setdefault('selector', "") - node.setdefault('extra_js', "") - - if node['major']: - node['selector'], node['extra_js'] = create_mv_selector(node) - - self.body.append(tmpl % node) - raise nodes.SkipNode - - -def create_mv_selector(node): - - mv_list = '' - - for x in range(node['min_ver'], node['max_ver'] + 1): - mv_list += build_mv_item(node['major'], x, node['releases']) - - selector_tmpl = """ -
-
- - -
-
-""" - - js_tmpl = """ - -""" - - selector_content = { - 'mv_list': mv_list - } - - js_content = { - 'min': node['min_ver'], - 'max': node['max_ver'] - } - - return selector_tmpl % selector_content, js_tmpl % js_content - - -def build_mv_item(major, micro, releases): - version = "%d.%d" % (major, micro) - if version in releases: - return '' % ( - version, version, releases[version].capitalize()) - else: - return '' % (version, version) - - -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 = ('api-site.css', 'api-site.js', 'combobox.js') - fonts = ( - 'glyphicons-halflings-regular.ttf', - 'glyphicons-halflings-regular.woff' - ) - if app.builder.name != 'html' or exception: - return - app.info('Copying assets: %s' % ', '.join(assets)) - app.info('Copying fonts: %s' % ', '.join(fonts)) - 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) - for font in fonts: - dest = os.path.join(app.builder.outdir, '_static/fonts', font) - source = os.path.abspath(os.path.dirname(__file__)) - copyfile(os.path.join(source, 'assets', font), dest) - - -def add_assets(app): - app.add_stylesheet('api-site.css') - app.add_javascript('api-site.js') - app.add_javascript('combobox.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') - app.add_config_value('os_api_ref_release_microversions', '', '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)) - app.add_node(http_code, - html=(http_code_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) - app.add_directive('rest_status_code', HTTPResponseCodeDirective) - - # 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__} diff --git a/os_api_ref/assets/api-site.css b/os_api_ref/assets/api-site.css deleted file mode 100644 index 519c778..0000000 --- a/os_api_ref/assets/api-site.css +++ /dev/null @@ -1,218 +0,0 @@ -tt.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; } - -.docs-book-wrapper { - width: 90% !important -} - -tbody>tr:nth-child(odd)>td, -tbody>tr:nth-child(odd)>th { - background-color: #f9f9f9; -} - - -td>p { - margin: 0 0 0.5em; -} - -.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 parameter tables 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-COPY { - background-color: #6666ff; -} -.label-COPY[href]:hover, -.label-COPY[href]:focus { - background-color: #6699ff; -} -.label-DELETE { - background-color: #d9534f; -} -.label-DELETE[href]:hover, -.label-DELETE[href]:focus { - background-color: #c9302c; -} - -.btn-detail:hover, .btn-detail:focus, -.btn-expand-all:hover, .btn-expand-all:focus { - color: #fff; - background-color: #3b6c91; - border-color: #269abc; -} - -.btn-detail, -.btn-expand-all { - color: #fff; - background-color: #2A4E68; -} - -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; -} - -p.url-subtitle { - color: #555; - font-weight: bold; -} - -.docs-body .section h1 { - display: block; -} - -div.docs-sidebar-toc > div > ul > li { - list-style-type: none; - font-size: 0.8em; - font-weight: bold; -} - -div.docs-sidebar-toc > div > ul { - padding-left: 20px -} - -div.docs-sidebar-toc > div > ul > li > ul > li { - list-style-type: disc; - font-weight: normal; -} - -div.docs-top-contents { - display: none; -} - -div.endpoint-container{ - padding-left: 15px; -} - -#expand-all { - margin-top: 23px; -} - -### Combobox Experiment -@media (min-width: 768px) { - .form-search .combobox-container, - .form-inline .combobox-container { - display: inline-block; - margin-bottom: 0; - vertical-align: top; - } - .form-search .combobox-container .input-group-addon, - .form-inline .combobox-container .input-group-addon { - width: auto; - } -} -.combobox-selected .caret { - display: none; -} -/* :not doesn't work in IE8 */ -.combobox-container:not(.combobox-selected) .glyphicon-remove { - display: none; -} -.typeahead-long { - max-height: 300px; - overflow-y: auto; -} -.control-group.error .combobox-container .add-on { - color: #B94A48; - border-color: #B94A48; -} -.control-group.error .combobox-container .caret { - border-top-color: #B94A48; -} -.control-group.warning .combobox-container .add-on { - color: #C09853; - border-color: #C09853; -} -.control-group.warning .combobox-container .caret { - border-top-color: #C09853; -} -.control-group.success .combobox-container .add-on { - color: #468847; - border-color: #468847; -} -.control-group.success .combobox-container .caret { - border-top-color: #468847; -} diff --git a/os_api_ref/assets/api-site.js b/os_api_ref/assets/api-site.js deleted file mode 100644 index 5d0b83e..0000000 --- a/os_api_ref/assets/api-site.js +++ /dev/null @@ -1,178 +0,0 @@ -(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 the 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); - } - - - $(document).ready(function(){ - $('#mv_select').combobox({appendId: '-visable'}); - $('#mv_select').on('change', function() { - var version = this.value; - if (version == "") { - reset_microversion(); - } else { - set_microversion(version); - } - }); - }); - - -})(); diff --git a/os_api_ref/assets/combobox.js b/os_api_ref/assets/combobox.js deleted file mode 100644 index d69a7fe..0000000 --- a/os_api_ref/assets/combobox.js +++ /dev/null @@ -1,462 +0,0 @@ -/* ============================================================= - * bootstrap-combobox.js v1.1.7 - * ============================================================= - * Copyright 2012 Daniel Farrell - * - * 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. - * ============================================================ */ - -!function( $ ) { - - "use strict"; - - /* COMBOBOX PUBLIC CLASS DEFINITION - * ================================ */ - - var Combobox = function ( element, options ) { - this.options = $.extend({}, $.fn.combobox.defaults, options); - this.template = this.options.template || this.template - this.$source = $(element); - this.$container = this.setup(); - this.$element = this.$container.find('input[type=text]'); - this.$target = this.$container.find('input[type=hidden]'); - this.$button = this.$container.find('.dropdown-toggle'); - this.$menu = $(this.options.menu).appendTo('body'); - this.matcher = this.options.matcher || this.matcher; - this.sorter = this.options.sorter || this.sorter; - this.highlighter = this.options.highlighter || this.highlighter; - this.shown = false; - this.selected = false; - this.refresh(); - this.transferAttributes(); - this.listen(); - }; - - Combobox.prototype = { - - constructor: Combobox - - , setup: function () { - var combobox = $(this.template()); - this.$source.before(combobox); - this.$source.hide(); - return combobox; - } - - , disable: function() { - this.$element.prop('disabled', true); - this.$button.attr('disabled', true); - this.disabled = true; - this.$container.addClass('combobox-disabled'); - } - - , enable: function() { - this.$element.prop('disabled', false); - this.$button.attr('disabled', false); - this.disabled = false; - this.$container.removeClass('combobox-disabled'); - } - , parse: function () { - var that = this - , map = {} - , source = [] - , selected = false - , selectedValue = ''; - this.$source.find('option').each(function() { - var option = $(this); - if (option.val() === '') { - that.options.placeholder = option.text(); - return; - } - map[option.text()] = option.val(); - source.push(option.text()); - if (option.prop('selected')) { - selected = option.text(); - selectedValue = option.val(); - } - }) - this.map = map; - if (selected) { - this.$element.val(selected); - this.$target.val(selectedValue); - this.$container.addClass('combobox-selected'); - this.selected = true; - } - return source; - } - - , transferAttributes: function() { - this.options.placeholder = this.$source.attr('data-placeholder') || this.options.placeholder - if(this.options.appendId !== "undefined") { - this.$element.attr('id', this.$source.attr('id') + this.options.appendId); - } - this.$element.attr('placeholder', this.options.placeholder) - this.$target.prop('name', this.$source.prop('name')) - this.$target.val(this.$source.val()) - this.$source.removeAttr('name') // Remove from source otherwise form will pass parameter twice. - this.$element.attr('required', this.$source.attr('required')) - this.$element.attr('rel', this.$source.attr('rel')) - this.$element.attr('title', this.$source.attr('title')) - this.$element.attr('class', this.$source.attr('class')) - this.$element.attr('tabindex', this.$source.attr('tabindex')) - this.$source.removeAttr('tabindex') - if (this.$source.attr('disabled')!==undefined) - this.disable(); - } - - , select: function () { - var val = this.$menu.find('.active').attr('data-value'); - this.$element.val(this.updater(val)).trigger('change'); - this.$target.val(this.map[val]).trigger('change'); - this.$source.val(this.map[val]).trigger('change'); - this.$container.addClass('combobox-selected'); - this.selected = true; - return this.hide(); - } - - , updater: function (item) { - return item; - } - - , show: function () { - var pos = $.extend({}, this.$element.position(), { - height: this.$element[0].offsetHeight - }); - - this.$menu - .insertAfter(this.$element) - .css({ - top: pos.top + pos.height - , left: pos.left - }) - .show(); - - $('.dropdown-menu').on('mousedown', $.proxy(this.scrollSafety, this)); - - this.shown = true; - return this; - } - - , hide: function () { - this.$menu.hide(); - $('.dropdown-menu').off('mousedown', $.proxy(this.scrollSafety, this)); - this.$element.on('blur', $.proxy(this.blur, this)); - this.shown = false; - return this; - } - - , lookup: function (event) { - this.query = this.$element.val(); - return this.process(this.source); - } - - , process: function (items) { - var that = this; - - items = $.grep(items, function (item) { - return that.matcher(item); - }) - - items = this.sorter(items); - - if (!items.length) { - return this.shown ? this.hide() : this; - } - - return this.render(items.slice(0, this.options.items)).show(); - } - - , template: function() { - if (this.options.bsVersion == '2') { - return '
' - } else { - return '
' - } - } - - , matcher: function (item) { - return ~item.toLowerCase().indexOf(this.query.toLowerCase()); - } - - , sorter: function (items) { - var beginswith = [] - , caseSensitive = [] - , caseInsensitive = [] - , item; - - while (item = items.shift()) { - if (!item.toLowerCase().indexOf(this.query.toLowerCase())) {beginswith.push(item);} - else if (~item.indexOf(this.query)) {caseSensitive.push(item);} - else {caseInsensitive.push(item);} - } - - return beginswith.concat(caseSensitive, caseInsensitive); - } - - , highlighter: function (item) { - var query = this.query.replace(/[\-\[\]{}()*+?.,\\\^$|#\s]/g, '\\$&'); - return item.replace(new RegExp('(' + query + ')', 'ig'), function ($1, match) { - return '' + match + ''; - }) - } - - , render: function (items) { - var that = this; - - items = $(items).map(function (i, item) { - i = $(that.options.item).attr('data-value', item); - i.find('a').html(that.highlighter(item)); - return i[0]; - }) - - items.first().addClass('active'); - this.$menu.html(items); - return this; - } - - , next: function (event) { - var active = this.$menu.find('.active').removeClass('active') - , next = active.next(); - - if (!next.length) { - next = $(this.$menu.find('li')[0]); - } - - next.addClass('active'); - } - - , prev: function (event) { - var active = this.$menu.find('.active').removeClass('active') - , prev = active.prev(); - - if (!prev.length) { - prev = this.$menu.find('li').last(); - } - - prev.addClass('active'); - } - - , toggle: function () { - if (!this.disabled) { - if (this.$container.hasClass('combobox-selected')) { - this.clearTarget(); - this.triggerChange(); - this.clearElement(); - } else { - if (this.shown) { - this.hide(); - } else { - this.clearElement(); - this.lookup(); - } - } - } - } - - , scrollSafety: function(e) { - if (e.target.tagName == 'UL') { - this.$element.off('blur'); - } - } - , clearElement: function () { - this.$element.val('').focus(); - } - - , clearTarget: function () { - this.$source.val(''); - this.$target.val(''); - this.$container.removeClass('combobox-selected'); - this.selected = false; - } - - , triggerChange: function () { - this.$source.trigger('change'); - } - - , refresh: function () { - this.source = this.parse(); - this.options.items = this.source.length; - } - - , listen: function () { - this.$element - .on('focus', $.proxy(this.focus, this)) - .on('blur', $.proxy(this.blur, this)) - .on('keypress', $.proxy(this.keypress, this)) - .on('keyup', $.proxy(this.keyup, this)); - - if (this.eventSupported('keydown')) { - this.$element.on('keydown', $.proxy(this.keydown, this)); - } - - this.$menu - .on('click', $.proxy(this.click, this)) - .on('mouseenter', 'li', $.proxy(this.mouseenter, this)) - .on('mouseleave', 'li', $.proxy(this.mouseleave, this)); - - this.$button - .on('click', $.proxy(this.toggle, this)); - } - - , eventSupported: function(eventName) { - var isSupported = eventName in this.$element; - if (!isSupported) { - this.$element.setAttribute(eventName, 'return;'); - isSupported = typeof this.$element[eventName] === 'function'; - } - return isSupported; - } - - , move: function (e) { - if (!this.shown) {return;} - - switch(e.keyCode) { - case 9: // tab - case 13: // enter - case 27: // escape - e.preventDefault(); - break; - - case 38: // up arrow - e.preventDefault(); - this.prev(); - this.fixMenuScroll(); - break; - - case 40: // down arrow - e.preventDefault(); - this.next(); - this.fixMenuScroll(); - break; - } - - e.stopPropagation(); - } - - , fixMenuScroll: function(){ - var active = this.$menu.find('.active'); - if(active.length){ - var top = active.position().top; - var bottom = top + active.height(); - var scrollTop = this.$menu.scrollTop(); - var menuHeight = this.$menu.height(); - if(bottom > menuHeight){ - this.$menu.scrollTop(scrollTop + bottom - menuHeight); - } else if(top < 0){ - this.$menu.scrollTop(scrollTop + top); - } - } - } - - , keydown: function (e) { - this.suppressKeyPressRepeat = ~$.inArray(e.keyCode, [40,38,9,13,27]); - this.move(e); - } - - , keypress: function (e) { - if (this.suppressKeyPressRepeat) {return;} - this.move(e); - } - - , keyup: function (e) { - switch(e.keyCode) { - case 40: // down arrow - if (!this.shown){ - this.toggle(); - } - break; - case 39: // right arrow - case 38: // up arrow - case 37: // left arrow - case 36: // home - case 35: // end - case 16: // shift - case 17: // ctrl - case 18: // alt - break; - - case 9: // tab - case 13: // enter - if (!this.shown) {return;} - this.select(); - break; - - case 27: // escape - if (!this.shown) {return;} - this.hide(); - break; - - default: - this.clearTarget(); - this.lookup(); - } - - e.stopPropagation(); - e.preventDefault(); - } - - , focus: function (e) { - this.focused = true; - } - - , blur: function (e) { - var that = this; - this.focused = false; - var val = this.$element.val(); - if (!this.selected && val !== '' ) { - this.$element.val(''); - this.$source.val('').trigger('change'); - this.$target.val('').trigger('change'); - } - if (!this.mousedover && this.shown) {setTimeout(function () { that.hide(); }, 200);} - } - - , click: function (e) { - e.stopPropagation(); - e.preventDefault(); - this.select(); - this.$element.focus(); - } - - , mouseenter: function (e) { - this.mousedover = true; - this.$menu.find('.active').removeClass('active'); - $(e.currentTarget).addClass('active'); - } - - , mouseleave: function (e) { - this.mousedover = false; - } - }; - - /* COMBOBOX PLUGIN DEFINITION - * =========================== */ - $.fn.combobox = function ( option ) { - return this.each(function () { - var $this = $(this) - , data = $this.data('combobox') - , options = typeof option == 'object' && option; - if(!data) {$this.data('combobox', (data = new Combobox(this, options)));} - if (typeof option == 'string') {data[option]();} - }); - }; - - $.fn.combobox.defaults = { - bsVersion: '3' - , menu: '
    ' - , item: '
    • ' - }; - - $.fn.combobox.Constructor = Combobox; - -}( window.jQuery ); diff --git a/os_api_ref/assets/glyphicons-halflings-regular.ttf b/os_api_ref/assets/glyphicons-halflings-regular.ttf deleted file mode 100644 index 1413fc6..0000000 Binary files a/os_api_ref/assets/glyphicons-halflings-regular.ttf and /dev/null differ diff --git a/os_api_ref/assets/glyphicons-halflings-regular.woff b/os_api_ref/assets/glyphicons-halflings-regular.woff deleted file mode 100644 index 9e61285..0000000 Binary files a/os_api_ref/assets/glyphicons-halflings-regular.woff and /dev/null differ diff --git a/os_api_ref/http_codes.py b/os_api_ref/http_codes.py deleted file mode 100644 index fdabdbf..0000000 --- a/os_api_ref/http_codes.py +++ /dev/null @@ -1,237 +0,0 @@ -# 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 docutils import nodes -from docutils.parsers.rst.directives.tables import Table -from docutils.statemachine import ViewList -from six.moves.http_client import responses -import yaml - -# cache for file -> yaml so we only do the load and check of a yaml -# file once during a sphinx processing run. -HTTP_YAML_CACHE = {} - - -class HTTPResponseCodeDirective(Table): - - headers = ["Code", "Reason"] - - status_types = ("success", "error") - - # This is for HTTP response codes that OpenStack may use that are not part - # the httplib response dict. - CODES = { - 429: "Too Many Requests", - } - - required_arguments = 2 - - def __init__(self, *args, **kwargs): - self.CODES.update(responses) - super(HTTPResponseCodeDirective, self).__init__(*args, **kwargs) - - def _load_status_file(self, fpath): - global HTTP_YAML_CACHE - if fpath in HTTP_YAML_CACHE: - return HTTP_YAML_CACHE[fpath] - - # self.app.info("Fpath: %s" % fpath) - try: - with open(fpath, 'r') as stream: - lookup = yaml.safe_load(stream) - except IOError: - self.app.warn( - "Parameters file %s not found" % fpath, - (self.env.docname, None)) - return - except yaml.YAMLError as exc: - self.app.warn(exc) - raise - - HTTP_YAML_CACHE[fpath] = lookup - return lookup - - 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) >= 2: - error = self.state_machine.reporter.error( - '%s' % self.arguments, - nodes.literal_block(self.block_text, self.block_text), - line=self.lineno) - return [error] - - _, status_defs_file = self.env.relfn2path(self.arguments.pop()) - status_type = self.arguments.pop() - - self.status_defs = self._load_status_file(status_defs_file) - - # self.app.info("%s" % str(self.status_defs)) - - if status_type not in self.status_types: - error = self.state_machine.reporter.error( - 'Type %s is not one of %s' % (status_type, self.status_types), - nodes.literal_block(self.block_text, self.block_text), - line=self.lineno) - return [error] - - self.yaml = self._load_codes() - - 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'] = [30, 70] - self.col_widths = self.get_column_widths(self.max_cols) - if isinstance(self.col_widths, tuple): - # In docutils 0.13.1, get_column_widths returns a (widths, - # colwidths) tuple, where widths is a string (i.e. 'auto'). - # See https://sourceforge.net/p/docutils/patches/120/. - self.col_widths = self.col_widths[1] - # 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) - - title_block = nodes.title( - text=status_type.capitalize()) - - section = nodes.section(ids=title_block) - section += title_block - section += table_node - - return [section] + messages - - def _load_codes(self): - content = "\n".join(self.content) - parsed = yaml.safe_load(content) - - new_content = list() - - for item in parsed: - if isinstance(item, int): - new_content.append((item, self.status_defs[item]['default'])) - else: - try: - for code, reason in item.items(): - new_content.append( - (code, self.status_defs[code][reason]) - ) - except KeyError: - self.app.warn( - "Could not find %s for code %s" % (reason, code)) - new_content.append( - (code, self.status_defs[code]['default'])) - - return new_content - - 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 add_col(self, node): - entry = nodes.entry() - entry.append(node) - return entry - - def add_desc_col(self, value): - entry = nodes.entry() - result = ViewList(value.split('\n')) - self.state.nested_parse(result, 0, entry) - return entry - - def collect_rows(self): - rows = [] - groups = [] - try: - # self.app.info("Parsed content is: %s" % self.yaml) - for code, desc in self.yaml: - - h_code = http_code() - h_code['code'] = code - h_code['title'] = self.CODES.get(code, 'Unknown') - - trow = nodes.row() - trow += self.add_col(h_code) - trow += self.add_desc_col(desc) - rows.append(trow) - except AttributeError as exc: - # if 'key' in locals(): - self.app.warn("Failure on key: %s, values: %s. %s" % - (code, desc, exc)) - # else: - # rows.append(self.show_no_yaml_error()) - return rows, groups - - -def http_code_html(self, node): - tmpl = "%(code)s - %(title)s" - self.body.append(tmpl % node) - raise nodes.SkipNode - - -class http_code(nodes.Part, nodes.Element): - """Node for http_code stanza - - Because we need to insert very specific HTML at the final stage of - processing, the http_code 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 diff --git a/os_api_ref/tests/__init__.py b/os_api_ref/tests/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/os_api_ref/tests/base.py b/os_api_ref/tests/base.py deleted file mode 100644 index 730258f..0000000 --- a/os_api_ref/tests/base.py +++ /dev/null @@ -1,95 +0,0 @@ -# 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()) diff --git a/os_api_ref/tests/examples/basic/conf.py b/os_api_ref/tests/examples/basic/conf.py deleted file mode 100644 index 997da6d..0000000 --- a/os_api_ref/tests/examples/basic/conf.py +++ /dev/null @@ -1,35 +0,0 @@ -# -# 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. - -import openstackdocstheme - -html_theme = 'openstackdocs' -html_theme_path = [openstackdocstheme.get_html_theme_path()] -html_theme_options = { - "sidebar_mode": "toc", -} - -extensions = [ - 'os_api_ref', -] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' diff --git a/os_api_ref/tests/examples/basic/index.rst b/os_api_ref/tests/examples/basic/index.rst deleted file mode 100644 index 80e717f..0000000 --- a/os_api_ref/tests/examples/basic/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. rest_expand_all:: - -I am text, hear me roar! - -============== - List Servers -============== - -.. rest_method:: GET /servers - -.. rest_parameters:: parameters.yaml - - - name: name - -Response codes --------------- - -.. rest_status_code:: success status.yaml - - - 200 - - 100 - - 201 - - -.. rest_status_code:: error status.yaml - - - 405 - - 403 - - 401 - - 400 - - 500 - - 409: duplcate_zone diff --git a/os_api_ref/tests/examples/basic/parameters.yaml b/os_api_ref/tests/examples/basic/parameters.yaml deleted file mode 100644 index 68f5c52..0000000 --- a/os_api_ref/tests/examples/basic/parameters.yaml +++ /dev/null @@ -1,6 +0,0 @@ -name: - in: body - required: true - type: string - description: | - The name of things diff --git a/os_api_ref/tests/examples/basic/status.yaml b/os_api_ref/tests/examples/basic/status.yaml deleted file mode 100644 index d21f2c2..0000000 --- a/os_api_ref/tests/examples/basic/status.yaml +++ /dev/null @@ -1,39 +0,0 @@ -################# -# Success Codes # -################# -100: - default: | - An unusual code for an API -200: - default: | - Request was successful. -201: - default: | - Resource was created and is ready to use. - -################# -# Error Codes # -################# - -400: - default: | - Some content in the request was invalid - zone_data_error: | - Some of the data for the -401: - default: | - User must authenticate before making a request -403: - default: | - Policy does not allow current user to do this operation. -405: - default: | - Method is not valid for this endpoint. -409: - default: | - This operation conflicted with another operation on this resource - duplcate_zone: | - There is already a zone with this name. -500: - default: | - Something went wrong inside the service. diff --git a/os_api_ref/tests/examples/microversions/conf.py b/os_api_ref/tests/examples/microversions/conf.py deleted file mode 100644 index e57a0fd..0000000 --- a/os_api_ref/tests/examples/microversions/conf.py +++ /dev/null @@ -1,38 +0,0 @@ -# -# 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. - -import openstackdocstheme - -html_theme = 'openstackdocs' -html_theme_path = [openstackdocstheme.get_html_theme_path()] -html_theme_options = { - "sidebar_mode": "toc", -} - -extensions = [ - 'os_api_ref', -] - -# 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' diff --git a/os_api_ref/tests/examples/microversions/index.rst b/os_api_ref/tests/examples/microversions/index.rst deleted file mode 100644 index 33a8886..0000000 --- a/os_api_ref/tests/examples/microversions/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. 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 diff --git a/os_api_ref/tests/examples/microversions/parameters.yaml b/os_api_ref/tests/examples/microversions/parameters.yaml deleted file mode 100644 index 8b02094..0000000 --- a/os_api_ref/tests/examples/microversions/parameters.yaml +++ /dev/null @@ -1,20 +0,0 @@ -name: - 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.20 \ No newline at end of file diff --git a/os_api_ref/tests/examples/warnings/conf.py b/os_api_ref/tests/examples/warnings/conf.py deleted file mode 100644 index 997da6d..0000000 --- a/os_api_ref/tests/examples/warnings/conf.py +++ /dev/null @@ -1,35 +0,0 @@ -# -# 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. - -import openstackdocstheme - -html_theme = 'openstackdocs' -html_theme_path = [openstackdocstheme.get_html_theme_path()] -html_theme_options = { - "sidebar_mode": "toc", -} - -extensions = [ - 'os_api_ref', -] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' diff --git a/os_api_ref/tests/examples/warnings/empty_parameters_file.yaml b/os_api_ref/tests/examples/warnings/empty_parameters_file.yaml deleted file mode 100644 index 54bd776..0000000 --- a/os_api_ref/tests/examples/warnings/empty_parameters_file.yaml +++ /dev/null @@ -1 +0,0 @@ -# Empty parameter file diff --git a/os_api_ref/tests/examples/warnings/index.rst b/os_api_ref/tests/examples/warnings/index.rst deleted file mode 100644 index 42041f0..0000000 --- a/os_api_ref/tests/examples/warnings/index.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. 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 - - invalid_name - - -No Parameters Specified ------------------------ - -.. rest_parameters:: parameters.yaml - - - -Empty File and Parameters Specified ------------------------------------ - -.. rest_parameters:: empty_parameters_file.yaml - - - name: name - -Nonexistent Parameter File --------------------------- - -.. rest_parameters:: no_parameters.yaml - - -Check missing path parameters in stanza ---------------------------------------- - -.. rest_method:: GET /server/{server_id}/{new_id}/{new_id2} - -.. rest_parameters:: parameters.yaml - - - server_id: server_id - -Check another missing path parameters in stanza ------------------------------------------------ - -.. rest_method:: GET /server/{b_id}/{c_id2}/{server_id} - -.. rest_parameters:: parameters.yaml - - - server_id: server_id diff --git a/os_api_ref/tests/examples/warnings/parameters.yaml b/os_api_ref/tests/examples/warnings/parameters.yaml deleted file mode 100644 index 831a8fe..0000000 --- a/os_api_ref/tests/examples/warnings/parameters.yaml +++ /dev/null @@ -1,25 +0,0 @@ -# valid path parameter -server_id: - description: | - ID for server. - in: path - required: true - type: string -# 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 diff --git a/os_api_ref/tests/test_basic_example.py b/os_api_ref/tests/test_basic_example.py deleted file mode 100644 index d746100..0000000 --- a/os_api_ref/tests/test_basic_example.py +++ /dev/null @@ -1,163 +0,0 @@ -# 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 = """ ------ - - - - - - - - - - - - - - -
    NameInTypeDescription
    namebodystringThe name of things
    """ - - self.assertIn(table, self.content) - - def test_rest_response(self): - - success_table = """table border="1" class="docutils"> - - - - - -Code -Reason - - - -200 - OK -Request was successful. - -100 - Continue -An unusual code for an API - -201 - Created -Resource was created and is ready to use. - - - -""" - - error_table = """ ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
    CodeReason
    405 - Method Not AllowedMethod is not valid for this endpoint.
    403 - ForbiddenPolicy does not allow current user to do this operation.
    401 - UnauthorizedUser must authenticate before making a request
    400 - Bad RequestSome content in the request was invalid
    500 - Internal Server ErrorSomething went wrong inside the service.
    409 - ConflictThere is already a zone with this name.
    -""" - self.assertIn(success_table, self.content) - self.assertIn(error_table, self.content) diff --git a/os_api_ref/tests/test_microversions.py b/os_api_ref/tests/test_microversions.py deleted file mode 100644 index 1f8e92b..0000000 --- a/os_api_ref/tests/test_microversions.py +++ /dev/null @@ -1,106 +0,0 @@ -# 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 = """
    - ------ - - - - - - - - - - - - - - - - - - - - - - - - -
    NameInTypeDescription
    namebodystringThe name of things
    name2bodystring

    The name of things

    -

    New in version 2.11

    -
    name3bodystring

    The name of things

    -

    Deprecated in version 2.20

    -
    -
    -""" # noqa - self.assertIn(table, self.content) - - def test_mv_selector(self): - - button_selectors = '' # noqa - 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) diff --git a/os_api_ref/tests/test_os_api_ref.py b/os_api_ref/tests/test_os_api_ref.py deleted file mode 100644 index 7edef37..0000000 --- a/os_api_ref/tests/test_os_api_ref.py +++ /dev/null @@ -1,26 +0,0 @@ -# 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 diff --git a/os_api_ref/tests/test_warnings.py b/os_api_ref/tests/test_warnings.py deleted file mode 100644 index 7c3a5f2..0000000 --- a/os_api_ref/tests/test_warnings.py +++ /dev/null @@ -1,101 +0,0 @@ -# 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 a 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'"), - self.warning) - - def test_invalid_parameter_definition(self): - """Warning when parameter definition is invalid.""" - self.assertIn( - ("WARNING: Invalid parameter definition ``invalid_name``. " - + "Expected format: ``name: reference``. "), - self.warning) - - def test_empty_parameter_file(self): - """Warning when parameter file exists but is empty.""" - self.assertIn( - ("WARNING: Parameters file is empty"), - self.warning) - - def test_no_parameters_set(self): - """Error when parameters are not set in rest_parameters stanza.""" - self.assertIn( - ("No parameters defined\n\n.." - + " rest_parameters:: parameters.yaml"), - self.warning) - - def test_parameter_file_not_exist(self): - """Error when parameter file does not exist""" - self.assertIn( - ("No parameters defined\n\n.." - + " rest_parameters:: no_parameters.yaml"), - self.warning) - - def test_missing_path_parameter_in_stanza(self): - """Warning when path param not found in rest_parameter stanza.""" - - self.assertIn( - ("WARNING: No path parameter ``b_id`` found in" - + " rest_parameter stanza.\n"), - self.warning) diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index e3aca41..0000000 --- a/requirements.txt +++ /dev/null @@ -1,9 +0,0 @@ -# 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!=2.1.0,>=2.0.0 # Apache-2.0 -PyYAML>=3.10.0 # MIT -six>=1.9.0 # MIT -sphinx!=1.6.1,>=1.5.1 # BSD -openstackdocstheme>=1.5.0 # Apache-2.0 diff --git a/setup.cfg b/setup.cfg deleted file mode 100644 index 6aea994..0000000 --- a/setup.cfg +++ /dev/null @@ -1,46 +0,0 @@ -[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://docs.openstack.org/developer/os-api-ref -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.4 - -[files] -packages = - os_api_ref - -[build_sphinx] -source-dir = doc/source -build-dir = doc/build -all_files = 1 -warning-is-error = 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 diff --git a/setup.py b/setup.py deleted file mode 100644 index 566d844..0000000 --- a/setup.py +++ /dev/null @@ -1,29 +0,0 @@ -# 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>=2.0.0'], - pbr=True) diff --git a/test-requirements.txt b/test-requirements.txt deleted file mode 100644 index 4b21de3..0000000 --- a/test-requirements.txt +++ /dev/null @@ -1,13 +0,0 @@ -# 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.13.0,<0.14,>=0.12.0 # Apache-2.0 - -coverage!=4.4,>=4.0 # Apache-2.0 -python-subunit>=0.0.18 # Apache-2.0/BSD -oslosphinx>=4.7.0 # Apache-2.0 -testrepository>=0.0.18 # Apache-2.0/BSD -testtools>=1.4.0 # MIT -sphinx-testing # BSD License -beautifulsoup4 # MIT diff --git a/tools/tox_install.sh b/tools/tox_install.sh deleted file mode 100755 index e61b63a..0000000 --- a/tools/tox_install.sh +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env bash - -# Client constraint file contains this client version pin that is in conflict -# with installing the client from source. We should remove the version pin in -# the constraints file before applying it for from-source installation. - -CONSTRAINTS_FILE="$1" -shift 1 - -set -e - -# NOTE(tonyb): Place this in the tox enviroment's log dir so it will get -# published to logs.openstack.org for easy debugging. -localfile="$VIRTUAL_ENV/log/upper-constraints.txt" - -if [[ "$CONSTRAINTS_FILE" != http* ]]; then - CONSTRAINTS_FILE="file://$CONSTRAINTS_FILE" -fi -# NOTE(tonyb): need to add curl to bindep.txt if the project supports bindep -curl "$CONSTRAINTS_FILE" --insecure --progress-bar --output "$localfile" - -pip install -c"$localfile" openstack-requirements - -# This is the main purpose of the script: Allow local installation of -# the current repo. It is listed in constraints file and thus any -# install will be constrained and we need to unconstrain it. -edit-constraints "$localfile" -- "$CLIENT_NAME" - -pip install -c"$localfile" -U "$@" -exit $? diff --git a/tox.ini b/tox.ini deleted file mode 100644 index 408702f..0000000 --- a/tox.ini +++ /dev/null @@ -1,38 +0,0 @@ -[tox] -minversion = 2.0 -envlist = py27,pep8,docs -skipsdist = True - -[testenv] -setenv = - VIRTUAL_ENV={envdir} - BRANCH_NAME=master - CLIENT_NAME=os-api-ref -install_command = {toxinidir}/tools/tox_install.sh {env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt} {opts} {packages} - 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