Versions older than Zed are now either Unmaintained or EOL. In order to
avoid readers selecting those versions by mistake, bump the default
value for earliest_published_series from mitake to zed. Documentation
for older versions is still published and accessible via direct links.
Projects that want their readers to still access older documentation via
the version selector can do so by overriding the
earliest_published_series value in their docs config.
Change-Id: I5a0cfcdc787f7fcf814526de761ea54479ab30db
Currently series names like 2023.1 and later appear at the end of the
version selector, but they are the most recent releases and thus should
be sorted to appear at the beginning.
Also make sure that a series doesn't appear twice in the list, which can
currently happen if e.g. the stable/victoria and unmaintained/victoria
branches exist at the same time during the transition.
Change-Id: Ide82c6de41081b9adcea632e41a581db5bc340c4
Since stable/yoga renamed to unmaintained/yoga the version is not
shown in the dropdown list of the available versions on the
https://docs.openstack.org in almost all projects. This change fixes
the issue.
Change-Id: I4f5f1bec04be3152c0f23ac17e450a1fd6fe91d4
Signed-off-by: Maksim Malchuk <maksim.malchuk@gmail.com>
Environment.srcdir is now a pathlib.Path object rather than string [1].
[1] https://github.com/sphinx-doc/sphinx/commit/49d8304670
Change-Id: Ifd26e2dd2fa36bbc9b0335db08e698db638de26d
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
The intention here was probably to include basic.css from Sphinx'
basic theme, but the correct way to reference it is just "basic.css".
This is what sphinx/themes/basic/theme.conf in Sphinx itself does.
Using "css/basic.css" caused the file to be not copied, and the
reference was 404.
Change-Id: Ifd6a78cb2dce42027f404829e1865fdb90acdb4f
Now that we inherit from basic/layout.html, these files are included
automatically in scripts block, so no need to repeat them in footer.
Also, underscore.js is not shipped anymore in Sphinx ≥ 6, so including
it caused a broken reference.
Change-Id: If0ffae7ced13d68380570a7eee949ac6e06c1743
The 'href' attribute is not valid for a <button> element, while the
'aria-labelledby' attribute must point to a valid element. It does not.
While we're here, we also fix indentation.
Change-Id: I3e15062b0f0306fbdc2ef82376a07e2b6943aeda
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
A <li> HTML element "must be contained in a parent element: an ordered
list (<ol>), an unordered list (<ul>), or a menu (<menu>)." [1]
[1] https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li
Change-Id: I9920b63d7dda2051ecfd4865cab4187533f70c07
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
In change I48b923a67010c92945c46ab00de0b090ba7cd465, way back in 2016,
we started hiding duplicate titles caused by us including the first h1
title we found at the top of the page. Unfortunately, the fix for this
was to hide *all* h1 titles found in the main docs body. Sphinx doesn't
insist on only a single h1 title (in fact, the sphinx-quickstart tool
produces an index.rst with two h1 titles) which means we were hiding a
lot of information unwittingly. Fix this by only hiding the first title,
as originally intended.
Also replace deprecated whitelist_externals by allowlist_externals
in tox.ini.
Change-Id: Ic8fc5e1256b4ab8925401fe6781210729a68d2aa
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
The footers haven't been refreshed in a while. Preferred links for
some things have changed, particularly since the foundation's
rename. Some of the old links in here have stopped working entirely.
Brush up everything to be more consistent with what's on the
foundation-maintained www.openstack.org site.
Change-Id: Iadc7642adb5d7e614ac022bd370bf46386a595e0
The top level MARKETPLACE link in many projects is broken.
It currently shows as: https://www.openstack.orgmarketplace/
This PR adds the missing forward slash.
Change-Id: I9da6ecf8c18546a9314b62b49058399f63de343a
changed links/texts to avoid sending people to the old Summit site
Signed-off-by: smarcet <smarcet@gmail.com>
Change-Id: I4fd61417093a1e452fbe3baf50d523e430e81142
The OpenStack project documentations pages that implement the "Search"
capability (:ref: 'search') are not working after the recent update to
sphinx 3.4.x. The search will never end and the browser will report a
Uncaught ReferenceError: Stemmer is not defined error.
This patch updates the openstackdocstheme to fix the search capability
by including the language_data.js that now provides the "Stemmer" function.
Closes-Bug: #1957717
Change-Id: If54b3b253ed7585f6f8b20f1e0f945101ef283a3
Previous commits addrressed some of the changes of Sphinx4 producting
different structure. The same is valid for the page heading where
instead of `<div class="section">` it produces `<section>`. This leads
to the css fix not to be appled and as such page heading present 2
times. Copy previous css fix with new path.
Change-Id: Ia9ab413280c2f98d041e0f5ae5c1df22c5a4a3f5
Sphinx 4.x changed how it includes some JavaScript files. Instead of
including them via the template, they are now injected using the
'add_js_file' function [1]. This relies on a custom Jinja2 function,
'js_tag' to generate the correct element with necessary attributes set.
Failure to use this results in missing attributes for some tags.
Rather than simply reworking our template to use this new function,
change how we use our 'layout.html' to instead override the 'basic'
template that Sphinx provides. This means we should get these kinds of
changes "for free" in the future, rather than having to worry about
them.
[1] https://github.com/sphinx-doc/sphinx/commit/a957d6f710
Change-Id: Idc0e6c1d38407fdadc29ea710069e74243c5c89a
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Sphinx 4.0 includes a newer version of docutils, which makes some
changes to the HTML 5 writer. Among these is the change in HTML
generated for the 'ObjectDescription' directive, which is used to
generate definition-list style output for things like oslo.config.
Previously, the title of each entry would be styled like so:
<dt id="DEFAULT.internal_service_availability_zone">
<code class="sig-name descname">
<span class="pre">internal_service_availability_zone</span>
</code>
</dt>
Now the improper use of the 'code' element is dropped, in favour of a
'span', like so:
<dt class="sig sig-object oslo.config" id="DEFAULT.internal_service_availability_zone">
<span class="sig-name descname">
<span class="pre">internal_service_availability_zone</span>
</span>
...
</dt>
Change-Id: I9fb9fbce6299600c3085bea1b8f17ad796bec4f8
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Commit 93cf1a57d [1] added a new parameter, 'name', to this function.
Include that when we detect Sphinx 4.x in use.
[1] https://github.com/sphinx-doc/sphinx/commit/93cf1a57d
Change-Id: I3b05df39f701280052d8a0d4f261e8749669ca11
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Updated Nav Menu to match https://www.openstack.org/ nav Menu
Signed-off-by: smarcet <smarcet@gmail.com>
Change-Id: Ib4e13a7964d548ed6bd9da683c4b755188ae7d6a
StarlingX is using the rST rubric directive to style headings such as
'Prerequisites', 'Procedure', and 'Results' in tasks without having them
appear in the TOC. There is currently no support for rubrics in the
StarlingX theme. This file appears to be the correct place to add it.
Testing to see if merge is picked up by StarlingX tox builds.
Change-Id: Ia339ad02522891c2b0b593dc782b67220565b87f
Signed-off-by: Stone <ronald.stone@windriver.com>
OpenStack Foundation got renamed to Open Infrastructure Foundation,
follow the rename and update links as well.
Remove no longer working links.
Change-Id: Iee3bb16fb6554ad80a3263f4f364976bcb8c88e1
Generating both the bug link and PDF download link requires some
configuration in 'conf.py': specifically, the 'openstack_bug_project'
and 'openstack_pdf_link' config options must be set. If these are not
present, the template doesn't include the relevant tags, which means
attempts to look these up via 'getElementById' will return 'null',
causing ugly tracebacks like so in the console.
Uncaught ReferenceError: bugProject is not defined
<anonymous> http://localhost:8000/search.html?q=usage:395
Simply surround these blocks with the same conditionals as the template,
avoiding the issue entirely.
Change-Id: I08ef0fc6c7ebd2c0e7ba89bc42cc92176fec8ab8
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Closes-Bug: #1896607
If we're unable to extract the project version from the package, we
leave things unversioned. Unfortunately, that means setting the
'version' and 'release' config options to 'None'. These should be
strings and setting them to 'None' results in the following errors:
WARNING: The config value `release' has type `NoneType', defaults to `str'.
...
Exception occurred:
File ".../sphinx/builders/html/__init__.py", line 475, in prepare_writing
'release': return_codes_re.sub('', self.config.release),
TypeError: expected string or bytes-like object
Simply set an empty string instead.
Change-Id: I6df4a90b04f3ed89c69fb7669027feda6c5ffe79
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Closes-Bug: #1896609
Sphinx 3.0.0 changed the behavior of JavaScript-based search utility,
changing the configuration option used to determine the suffix for
search results from 'html_file_suffix' to 'html_link_suffix' [1]. We
were manually overriding 'DOCUMENTATION_OPTIONS' and were not setting
the 'LINK_SUFFIX' attribute, which maps to this config option, meaning
our resulting URLs looked like 'fooundefined', where 'foo' is the name
of the file.
Add 'LINK_SUFFIX', resolving this issue.
[1] https://github.com/sphinx-doc/sphinx/commit/a717ffec78
Change-Id: I06488225cf0431e601f16e0f1047a6088a11d5bd
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Closes-bug: #1880331
Introduced changes:
- pre-commit config and rules
- Add pre-commit to pep8 gate, Flake8 is covered in the pre-commit hooks.
- Applying fixes for pre-commit compliance in all code.
Also commit hash will be used instead of version tags in pre-commit to
prevend arbitrary code from running in developer's machines.
pre-commit will be used to:
- trailing whitespace;
- Replaces or checks mixed line ending (mixed-line-ending);
- Forbid files which have a UTF-8 byte-order marker (check-byte-order-marker);
- Checks that non-binary executables have a proper
shebang (check-executables-have-shebangs);
- Check for files that contain merge conflict strings (check-merge-conflict);
- Check for debugger imports and py37+ breakpoint()
calls in python source (debug-statements);
- Attempts to load all yaml files to verify syntax (check-yaml);
- Run flake8 checks (flake8) (local)
For further details about tests please refer to:
https://github.com/pre-commit/pre-commit-hooks
Change-Id: I9b979afcd45e6a51252ccccb686b01beeb9157f8
Signed-off-by: Moisés Guimarães de Medeiros <moguimar@redhat.com>
This patch adds the version dropdown from the openstackdocstheme to the
starlingxdocstheme. Change will allow users to view different versions
of StarlingX documentation.
Change-Id: I44b797e00be065e36cb3e7b447c83f8ab5fd69b5
Signed-off-by: MCamp859 <maryx.camp@intel.com>
This patch adds the search related files from openstackdocstheme to
starlingxdocs to modify the scope of the the search to the StarlingX
documentation.
Change-Id: Iaa8d3066221eca603876c6266f8f211aef033bfd
Signed-off-by: Ildiko Vancsa <ildiko.vancsa@gmail.com>
Change Ic116367ea7c6fc6d78b70e9c115898bae6ec6d96 lowered the level of
many logs to reduce the noise seen in documentation builds. However,
change I3ff74030195b6a85ff4e4e3b62f367aa78f85b0a introduced some new
info-level logs. Downgrade these to debug to restore our quieter output.
Change-Id: I80b99dfecb3d1b4414bacecafc890d3b0f1c50e3
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
We (nova) see the following warnings in our documentation builds:
[openstackdocstheme] could not determine last_updated for 'genindex'
[openstackdocstheme] could not determine last_updated for 'search'
This makes sense, since these pages are automatically generated by
Sphinx. Filter out warnings to remove these.
Change-Id: Ic85bc4356bc5bf0f5bf5771d4e81bb2be72f6ff7
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
To fix version display in PDFs, move config changes to config-inited
event.
First config-inited is called, then
builder-inited is called after the builder is setup. The builder might
use values from the config to set internal values.
This happens with the latex builder that takes version and release and
puts them into internal values.
So far, openstackdocstheme used builder-inited and setting version and
release from the theme happened to late. Move all config settings to a
config-inited phase so that it is early - and thus the latex builder can
create PDFs with version numbers.
Change-Id: Icdd308ba13de56bab13e97e3afc6338a7181dcbf
In this case:
project = "Some random name"
openstackdocs_auto_name = False
openstackdocs_auto_version = True
The call packaging.get_version(project_name) would fail, like in
python-monascaclient change https://review.opendev.org/729023.
Fix the logic to use the real project name for getting the version.
Change-Id: I0cb51a6535936bdc009a34a5956434030dd6bec8
Dr. Jens Harbott