Problem: build error when `http_theme` is NOT 'openstackdocs'
Cause: `copy_assets` starts copying fonts into non-existing dir.
Measure: mkdir _static/fonts before copying
```
Extension error (os_api_ref):
Handler <function copy_assets at 0x7fd3c902f310> for event
'build-finished' threw an exception (exception: [Errno 2]
No such file or directory: '..../api-ref/build/html/_static/
fonts/glyphicons-halflings-regular.ttf')
```
Change-Id: I70d5455db3bb61060a54202c5e510493c81661d5
When an exception happens while executing the method `_load_param_file`,
the exception logging `LOG.exception(exc_info=exc)` will generate an
error.
A small snippet to reproduce the issue is the following code:
from sphinx.util import logging
LOG = logging.getLogger(__name__)
try:
raise Exception("teste")
except Exception as exc:
LOG.exception(exc_info=exc)
Which will generate the error:
Exception: teste
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "/home/rafael/git/os-api-ref/os_api_ref/test-logging.py", line 8, in <module>
LOG.exception(exc_info=exc)
TypeError: exception() missing 1 required positional argument: 'msg'
Process finished with exit code 1
With this fix, the exception logging error is solved, and users get a
meaningful message.
Change-Id: Ib3c3e93c283d86b9708c74e60c2ac5762dc2c222
There were only two small users. No need to keep the library around for
those.
Change-Id: Iad5d845b46852ce74962a134c8d250142f29c8e3
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
We currently see the following warnings when building a doc project
involving os-api-ref:
RemovedInSphinx40Warning: The app.add_stylesheet() is deprecated.
Please use app.add_css_file() instead.
RemovedInSphinx40Warning: The app.add_javascript() is deprecated.
Please use app.add_js_file() instead.
As the message would suggest, these methods were replaced by
'add_css_file' and 'add_js_file' in commits 3afc72fb [1] and f3168d98
[2], respectively. Both changes were first included in Sphinx 1.8, which
is lower than our current minimum, so there's no need to bump
requirements.
[1] https://github.com/sphinx-doc/sphinx/commit/3afc72fb
[2] https://github.com/sphinx-doc/sphinx/commit/f3168d98
Change-Id: I7f4d772adbcb9d592935b14c430ae3a62a60b6d1
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
The repo is Python 3 now, so update hacking to version 3.0 which
supports Python 3.
Fix problems found by updated hacking version.
Change-Id: I4a4ec207f87d3afb58b6427825ce9b3872823008
This was added in I10d90ac2f702153508bc6e607ed451c089276a4d and doesn't
appear to have been used anywhere. Remove it.
Change-Id: If29f203da9633f9174ed4ba94d70153962d195b9
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
A random value can still easily hit collision, and at least
one was found easily on the gates (gone with a recheck).
Moreover, the usage of a random target does not allow for ensuring
reproducible builds: the usage of an hash build from the node
content makes sure that the target is stable across different
runs of api-ref generation.
Change-Id: I3fcd8a4e5b0a66c9dbf34f4a4c472f3c93c46bb8
For projects that have multiple APIs documented simultaneously, if
the labels are the equal on more than one version of the API build
will fail due to duplicate label.
Adding a random number to minimize the chance of duplicate label.
Change-Id: Ic8434ce79630637a878fa64307796be0f3efe6d1
rtd uses 'readthedocs' and 'readthedocssinglehtmllocalmedia' as
builder names. os-api-ref expected 'html' as builder name to
handle the css files correctly.
This change adds the support for the rtd builders.
Change-Id: I21a5144ada79c8c95846ce961169e2505db27a56
Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>
This resolves a deprecation warning. It also allows us to stop storing
the 'app' variable just to enable logging.
Change-Id: I53c0f0d5cc61e32a8f1ac1d48816d2c56d82cc41
- Moved to py3 by default
- Moved to testr
- Updated docs venv to match PTI
- Fixed a slight py3 compat issue
- Added py35 and py36 jobs
Change-Id: Id3a8c1c30ecfe9b6538bff6357aecca7ecd0ed81
Signed-off-by: Graham Hayes <gr@ham.ie>
Given the following 'parameters.yaml' file:
resources_query_granular:
type: string
in: query
required: false
description: |
Some description here...
min_version: 1.22
Clearly 'min_version' is indented at the wrong level. However, the error
message is pretty much useless:
Exception occurred:
File "./os_api_ref/__init__.py", line 261, in _check_yaml_sorting
if value['in'] not in sections:
TypeError: string indices must be integers, not str
It's obvious we should be saying _what_ is causing this issue. Start
doing this by way of an exception.
Change-Id: If68f82de1e3bf37b1ab89f12adf78e0d8d123674
This call generates the following deprecation warning:
RemovedInSphinx17Warning: sphinx.util.compat.Directive is deprecated
and will be removed in Sphinx 1.7, please use docutils' instead.
Resolve this.
Change-Id: I1083d3d6f3e646249f187a1bdade61eecc93c7e0
Currently max_version field shows text as
"Deprecated in version %s" which seems confusing to show
deprecated fields vs removed fields.
For example: if any element is removed in x version, then we
tag that element in parameter.yaml with max_version: x-1. api-ref shows
that element as "Deprecated in version x-1" which seems confusing on
below interpretation:
- is that element deprecated in x-1 version?
- is that element only deprecated in x-1 version not removed?
But actually that element is removed in x and only available till x-1 version.
- https://developer.openstack.org/api-ref/compute/?expanded=evacuate-server-evacuate-action-detail
This commit try to describe max_version filed in more clear way.
Change-Id: I388c6e27c3d15e3bee645b7b56f8142e2f16d3d6
Python objects returned with Yaml.load() may be dangerous if you receive
a YAML document from an untrusted source such as the Internet.
The function yaml.safe_load() limits this ability to simple Python
objects like integers or lists.
In ordered_load we're adding a custom class so we have to use yaml.load.
In order to make it safe, set the base class to SafeLoader instead of
Loader.
Reference:
https://security.openstack.org/guidelines/dg_avoid-dangerous-input-parsing-libraries.html
Co-Authored-By: Monty Taylor <mordred@inaugust.com>
Change-Id: I3d5df9898c72c59ddab0ac7562b953e91f470220
Add an explicit onclick action for anchor links so that they set the
urlbar correctly. This long standing issue really sucks in sending
around links to people from API sites.
Change-Id: I449399836d2f327188b659a266b2e860e3ebb462
The following file(s) added utf-8 encoding but never used. So we can
remove them at all.
os_api_ref/tests/test_warnings.py
os_api_ref/tests/test_os_api_ref.py
os_api_ref/tests/test_microversions.py
os_api_ref/tests/test_basic_example.py
os_api_ref/tests/base.py
os_api_ref/__init__.py
Change-Id: If08e1b00f777a146e2c582f5a194e022a215066e
In docutils 0.13.1, the get_column_widths method of Table directive
returns a tuple, where the widths array is the second item.
Also, get_column_widths now has a “if type(self.widths) == list” check,
so use the list syntax when setting the widths property.
Change-Id: I9888a649313c60257ce6dfc46cfbd2dcbf7ac189
This does a few things:
* Change from button list to a select combo box.
** This allows users to type the number they want
* Add the ablity to tag versions to releases
** E.G. Say mitaka was released with 2.27, it will
show in the list as "2.27 - Mitaka".
** This currently set as a config option in
conf.py as a dict like:
os_api_ref_release_microversions = {
'2.27' : 'mitaka',
'2.10': 'liberty'
}
* Uses https://github.com/danielfarrell/bootstrap-combobox
** Apache Licenced
Change-Id: Ica7dd55cdbf413f03ea635aefb627a705132a73e
With very long URI paths the wrapping either
looks weird or there is no charecter for it to
wrap on.
This moves the URI to its own line, and moves some
of the other elements aroud slightly.
Also changes the font of the subtitle to make it more apparent.
Change-Id: I36e7420224f69eaa5f4dceb18d910b40377b76c4
-Tests warnings for missing and empty parameter files.
-Tests warnings when rest_parameter stanza lists
parameter file but no parameters.
Change-Id: Ic2c740a34964b1e23560102cc4e5c7fe0be63d50
This adds experimental support for a microversion selector. The
interface for this may well change over time. To currently use this we
need 2 values in the sphinx conf.py to specify min and max
microversions. If you don't have those added, nothing is changed in
the UI.
Use at your own risk. However it's much easier to get feedback if we
have this in the package.
Change-Id: Iaf7e117ea5792bb3b60c1fd0ae416b241ab89d65
Currently, when a parameter is formatted wrong sphinx dies with a
cryptic error message:
AttributeError: 'str' object has no attribute 'items'
This happens because the parameter is not recognized as dict.
This patch adds a check that ensures parameters are formatted correctly
by verifying that they're dicts.
Change-Id: I0140336cdcd9fd1d356d1fa50fd8dd15790ef8bd
This fixes the parsing of min_version and max_version in
parameters.yaml by treating things that look like floats as
strings. Otherwise 2.20 ends up folding to 2.2, which is definitely
not intentional.
This also adds a set of tests for microversion class setting in both
parameters in tables as well as in the method itself.
Change-Id: If2713fc4038e69d113cdaa7db0231a1d03f6223b
Most API Docs seem to colour code the HTTP methods to make
for easier reading.
This sets:
GET / HEAD - Blue
POST - Green
PATCH/PUT - Yellow
DELETE - Red
By reuseing some of the bootstrap label-* css.
Change-Id: Ic58edeb672ced1e66849c561133f272982abcb4e
I incorrectly assumed folks wouldn't diverge on the use of the in
value from where it was specified in the OpenAPI spec, but in looking
at the senlin code, I was wrong.
This produces a much more specific warning to explain what is wrong
with the parameters file.
Change-Id: Idffbd55dcd69d8f9ad988f74eb1b4be4b8a56667
This mirrors in the version of the sphinx extension from Nova commit
1f67ab311422234335cda0e21e74186524617904 which includes the warnings
for out of order parameters.yaml files.
Static assets are stored in the assets/ sub directory, which includes:
* bootstrap files (including fonts) - MIT licensed
* api-site specific js and css fixes
The extension is updated to move these assets into the build directory
when building html, and to register these assets when we first start
up.
pep8 126 error fixed, and E129 ignored (because it's not compatible
with emacs indentation, and annoys me).
This builds the Nova api-ref tree correctly, which is not bad for a
Friday afternoon.
Change-Id: Ifd4fd570c8dbd981564326486f79b826f059543f
Alexander Fadeev