OpenStack Foundation got renamed to Open Infrastructure Foundation,
follow the rename and update links as well.
Remove no longer working links.
Change-Id: Iee3bb16fb6554ad80a3263f4f364976bcb8c88e1
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>
Create new config options to optionally link to a generate PDF file that
is published at the same location as the html files.
Note that the preview will not be able to download the file since
the file is in a different location. The publishing job moves the PDF
file in the top-level directory.
Change-Id: I3ff74030195b6a85ff4e4e3b62f367aa78f85b0a
With version 2.1, we renamed options in the extension, let's use them
here as well.
Increase also requirements for reno and Sphinx.
Change-Id: Ica3cc991ad7bcc1626b805ede57c9c23e2538239
It's bad practice to not prefix config options with a unique identifier
corresponding to the package. Start doing just this using the
'openstackdocs_' prefix.
Change-Id: Ic86998ceaa921f7093ba86f979ea648a1d621d59
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
This leads to more predictable behavior.
Change-Id: I3a9d96c4896a0d5ccc85b74562d35852a837f29f
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Closes-Bug: #1843527
As we recently did with auto-versioning, make the setting of the package
name configurable.
Change-Id: Ia9f6dab3fe86b2fc7d6b54f81230b3b9723e5e03
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Rather than relying on magic values to determine whether we should
attempt to auto-version documentation, start checking the paths for
commonly unversioned source doc paths and add an explicit knob to turn
this on or off.
Change-Id: Iecc3fa6f20f1aa92fcffe2b8adb0cd0da1aa17e4
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Closes-Bug: #1843976
PDF files from openstackdocsstheme-tox-manuals-buildpdf(-starlingxpdf)
jobs were not fetched after recent changes in the related zuul jobs.
This commit merges 'buildpdf' tox env into the 'docs' tox env
following the OpenStack PDF community goal convention.
The same change is made for starlingxdocs theme.
The .zuul.yaml file is updated accordingly.
Change-Id: I0081f77a19b71b093b3debf91e85a42cf2053471
Sphinx 2.0 switches the default HTML build from HTML4 to HTML5. HTML5
deprecates the 'border' attribute for the 'table' element and the HTML5
builder no longer emits this. This has resulted in a lack of borders on
tables.
Correct this by configuring border styling via CSS and then go a few
steps further and start colouring the table header and using zebra
stripes on rows to help visually distinguish them further. A sample
table is added to the demo documentation so we've something to inspect
locally.
Change-Id: I79b40bb5700807ac8ad523a6e0a83cd21965346e
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Closes-Bug: #1828265
Using the app instance for logging is deprecated. Thus updates example
output to show using a logger instead.
Change-Id: I060dbb528d303a00bc4b4b91a0816e35b561e07b
Signed-off-by: Sean McGinnis <sean.mcginnis@gmail.com>
At the PTG the Docs team and dhellmann decided that openstackdocstheme
was the proper place to keep the modifications required to build
a theme for StarlingX and other OpenStack Foundation-related projects.
This is a minimal set of changes to support a second theme with a couple
of visual changes thrown in to make obvious that the correct theme
is being used. The remainder of the visual work will follow.
Both PNG and SVG versions of the logo are included.
Add an additional jobs to build the docs and PDF with the new theme.
Modify the wording in README.rst and the docs index page regarding
the distinction between openstackdocstheme the module and openstackdocs
and starlingxdocs the themes and their intended uses.
There are a number of hard-coded OpenStack-isms that will eventually
need to be addressed.
Change-Id: I594136a0ea66d61f60dafc6a853137470efc7d42
Signed-off-by: Dean Troyer <dtroyer@gmail.com>
On some sites (like the governance site) the navigation between
pages is included in the page content itself, making the global
section of the TOC unnecessary. This adds a new theme option
(display_global_toc_section) to allow to disable it.
Change-Id: Ib6fb3bd1a6a776be06bc09e2e4183ca909ea7b60
The theme displays "OpenStack Docs:" in the title and "Docs home"
in the tooltip, which makes it hard to reuse for other websites
(including the governance website). This patch makes the root title
("OpenStack Docs" by default) configurable.
Change-Id: I4140f62a328debf81703cddd17dd6364b5eab479
Initialize variable with False and not with empty string - the variable
is a boolean.
Update example.
Changed this so that
use_storybard = true
in doc/source/conf.py will not result in:
The config value `use_storyboard' has type `bool', defaults to `str'.
Change-Id: I2ed164b9b0badade702c50543ac1a5eea4d1867b
StoryBoard now display the project group in the URL and not anymore a
number. Allow setting the storyboard project group to the name now.
This implies setting a new variable to differentiate between Launchpad
and StoryBoard.
Change-Id: Ie6f8c48fffe04256ad07f22e95935f6f7257ea17
If a repo has no stable branches, we do not need to show the badge,
disable it automatically.
Also, disable it for releasenotes, api-guide and api-ref. These
documents are always published from master and are versionless.
This avoids changing most of the repositories to disable the badge.
Change-Id: I063af45e40bd41e27334638e2cf65ca0c9119e63
We do now display the badge for version even on repos that do not have
branches like https://docs.openstack.org/infra/manual . The reason is
that the test is against series - and we *always* set series, by default
to 'latest'.
Add a new option to disable showing of the badge called display_badge
and use it. Repos can set this as part of html options.
Disable showing the badge for api-ref test document.
Change-Id: I985b49412aa1848b915b8f0a2ff9e95867e420ca
Configure the 'html_last_updated_fmt', 'latex_engine' and
'latex_elements' attributes automatically. Documentation is updated to
reflect the fact that these no longer need to be configured by hand.
Change-Id: I429b981135e35845bf5ed70020abfef3deccbf90
This is currently done by pbr and we want to stop doing that. Start
overriding this via the 'builder-inited' event instead.
Change-Id: Ia2bdd815aac91bc191a4b965c4d07ea5aafa2f84
The latter are overly verbose, while the former have a natural synergy
with the 'doc' role provided by Sphinx.
Change-Id: Ib2fd91c1115270d3eb7d8197efdf4b5e8a7316a9
Add a new configuration option to automatically create documentation
link roles without users having to set up the links with
sphinx.ext.extlinks explicitly.
Change-Id: Ia46560665372748b1e303093c76a87af3b6938e5
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This reverts commit f0744a1675.
Manual configuration should be necessary only in the rarest of cases.
Revert this in preparation for a more automated case.
Change-Id: I18902de42d95d9427165e6f8ffa6cab303ea62ca
Related-Bug: #1732630
Documentation not located in 'doc/source' directory needs the
giturl value to make the source url correct.
Change-Id: I772a66de4680ba73ed79f8ea5481d6900f71fa82
Closes-Bug: #1732630
Follow https://review.openstack.org/#/c/508061 to remove
tools/tox_install.sh, we can build without it.
Create new doc/requirements.txt file with doc requirements to make them
optional. We cannot use ".[test]" with pip, it would still install
project with constraints and fail.
Change-Id: I4f1fa1fd3139a763222b0a0f18394a7660c62497
The ".. sidebar::" directive generates a <div class="sidebar">
which is expected to float to the right of the text. This adds the
CSS from the oslosphinx theme to support it.
Change-Id: If03ea2a3892746a0590f831989b2ada4a1850385
These appear to have been confusing sphinx, which caused test jobs
to fail since we treat sphinx warnings as errors.
Change-Id: I75c52c3451ab130e50da7ab3537eac7ca12ccf74
It is a good idea to describe which things are needed
for PDF generation using openstackdocstheme.
Change-Id: I343c1fb5853da396f4de28a5e9b236195dcd5f4d
Rather than linking to recent releases by version, link to the series
docs by name. This allows us to link to a more limited number of
"versions" but maintain those links indefinitely now that we are
planning to retain our documentation online for a more extended period
of time.
The implementation uses dulwich to identify the tags and branches
rather than using git via subprocess.
Change-Id: If691b257f5fba7e431a1acd9d1a03415f2d07420
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
When I updated the icon selector as part of
https://review.openstack.org/#/c/485290, I made an error in the logic
meaning that the icons appear next to only the first of each item.
This was part of an initial proposed solution, but isn't actually needed,
and causes multiple usages of versionadded etc to not have icons.
Change-Id: If1c1011d8a7ed1e78f2675eca7daf4e497a8bf9e
Having a page table of contents at the top of the content section of
pages with a lot of section headings means that users have to scroll
down significantly before they see any real content. Move the page toc
into the sidebar to avoid the need for scrolling.
The old theme style information for the page toc is updated to reflect
the new location.
The example docs in demo/index.rst are updated to include nested
headings for testing the layout of the list.
Change-Id: I47222a70e58267c409c0d8d2f0f460d54c5fa5dd
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This patch adds support for the versionadded, versionchanged and
deprecated tags. It also reduces the rather aggressive margins and
padding around the admonitions, so that they stack a little better,
and adds a missing icon to the 'seealso' admonition.
Adds example admonitions to the Demo documentation.
Change-Id: Ieb064b26980f885549660a80e2a2578b71a5e7b7
Point out the versions need to be found when this option is used.
With all the path changes, this is currently not the case for *any*
project.
Change-Id: Ie439db0bd5a1d5fbdb63eb3489a6c50bdf07ed6f
Lighten the background and darken the text colors in the
admonition.important box to make it easier to read the (important!)
text within.
Change-Id: Idb449c02a0a0832b5f379e53c373cc4dd1fe0e81