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>
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
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
There's no easy way to check whether the user is overwritten
latex_engine, so revert I3a9d96c4896a0d5ccc85b74562d35852a837f29f
partially and continue to always set latex_engine.
Not setting latex_engine to xelatex breaks a number of OpenStack
repositories that dependend on the default of xelatex in
openstackdocstheme.
Change-Id: I06f1d577d108fd8f16b5aad3e00725f55817ddba
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
Since version 1.20 of openstackdocstheme, html_last_updated_fmt does not
need to be set anymore, remove it's setting.
Change-Id: I913b76cc6b3128a420a6fc69e2dc88627d47bbfe
in order to make builds reproducible.
See https://reproducible-builds.org/ for why this is good
and https://reproducible-builds.org/specs/source-date-epoch/
for the definition of this variable.
Without this patch, building python-debtcollector from a tarball
that does not contain a .git dir varied for every build.
Change-Id: Iaf8bc1c559f5b149a48c9dd05beb0961365fda7e
Signed-off-by: Bernhard M. Wiedemann <bwiedemann@suse.de>
The user can choose
- if warnings should be ignored (SKIP_SPHINX_WARNINGS=1)
- if warnings on translation build should be on (SPHINX_WARNINGS_TRANS=1)
added an example to the previously releasenotes
Change-Id: I1486139fdbdef5dd4e00a38c9cb751a5ed7881c6
Look at the git history to determine the last time a page was modified
and use that date as the last-updated date instead of the default
value of the current time.
Change-Id: I80db00eb2016859e1095c6a1db952f17df3e00d6
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
Import from i18n repo the scripts get-lang-display-name.py and
build-docs.sh, update comments so that they are generic.
Add the two files to setup.cfg so that they get distributed with the
package and can be executed from tox for building of translated
documents.
Change-Id: I80fcb1ed857da8452b310e6707cce3940577a35a
Change I594136a0ea66d61f60dafc6a853137470efc7d42 broke the API of this
package with renaming get_openstack_logo_path which broke a couple
of users, readd it.
Change-Id: Ia2f6760e0f6f53d94a8d3358d5c4e2fe0a2d7bf3
We can use this as a starting point for further changes. These files
are copies of those from openstacdocs with most of the openstac-specific
bits removed. This way we can track additional changes made as we progress.
Change-Id: I41c2a7d63ba7796aa3cf3cc001e077d5de28a14d
Signed-off-by: Dean Troyer <dtroyer@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>
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
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
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
Release notes are version independent, so remove version/release
values. We've found that projects now require the service package
to be installed in order to build release notes, and this is entirely
due to the current convention of pulling in the version information.
Release notes should not need installation in order to build, so this
unnecessary version setting needs to be removed.
This is needed for new release notes publishing, see
I56909152975f731a9d2c21b2825b972195e48ee8 and the discussion starting
at
http://lists.openstack.org/pipermail/openstack-dev/2017-November/124480.html
.
Change-Id: I41c5f76b60c2d958c714af8b59f273315a227817
The double backticks (``) markup caused text to be displayed in
red with a pinkish background colour. The text is now displayed
in black and bold, the same size as the surrounding text.
Change-Id: Id73e828b69445aa9bf4c48bea84dd95fef16bc2b
Fixes-Bug: 1718256
This makes the search.html page that's generated by sphinx function as
the local search, and not the global google based swift_search. The
sphinx integrated search will mean that only documents linked to the
current tree will be returned, which also ensures that searching for
content in stable/pike doesn't jump you to mitaka answers. It also
brings back highlighting of search results which is a style rule that
was lost in the building of the openstackdocstheme.
We probably also want sidebar integration of this search field,
however this will at least mean hitting the search.html page will do
what people previously expected.
Change-Id: I747ad28658e12441ccad7081d15788f5d738dc5e
Per the Sphinx documentations:
next - The next document for the navigation. This variable is either
false or has two attributes link and title. The title contains HTML
markup.
prev - Like next, but for the previous page.
If using the title value inside an element attribute, we need to ensure
the HTML tags mentioned above are stripped. Failure to do so results in
corrupted output.
Change-Id: I5fde1e6fc4d7966fcd3e767c79535202f3b41a71
Closes-Bug: #1702328
Some pages have no sub titles (the second level of titles or more).
In this case, the title string "Contents" of page local TOC is
completely meaningless and confusing to readers.
It is nice if this title string is shown only when needed.
This can be done by checking 'display_toc' variable in the template.
[1] https://docs.openstack.org/ocata/networking-guide/intro.html
Change-Id: I4803dd7712438eb2cd5fb6084e904bd8c0c98740
Allows setting of bug_project to a storyboard project number
to redirect to project page on storyboard.openstack.org for
report a bug feature.
Also, add some minor cleanups to doc/source/conf.py.
Change-Id: Ia14d30bf0dda89c48dec0a7cc3b8dccc26dc8d86
Releasenote translation publishing is being prepared. 'locale_dirs'
needs to be defined in conf.py to generate translated version of the
release notes.
Note that this repository might not get translated release notes - or
no translations at all - but we add the entry here nevertheless to
prepare for it.
Change-Id: I8eac4be92199c7ba98badc1dac68be3e71140d40
- Adds a theme variable, sidebar_dropdown, to set
a dropdown menu for the API references.
To test, uncomment the parameter html_theme_options in
doc/source/conf.py OR build the API Ref demo docs.
- Adds an API Ref docs demo integrating os-api-ref
and openstackdocstheme. Tested with webserver:
python -m SimpleHTTPServer <port_num>.
Change-Id: I346695cd407ecf4efc0a5e00f2c0ccc1ea099ec5
In some cases, a user may want to disable the automatic table of
contents generation in the body of the page. This patch adds
a ``display_toc`` option into the theme options list that will
disable the automatic TOC in the documentation body.
Closes-Bug: 1613761
Change-Id: I508b46c5ba6a022ee4ad2687cb4e44ed449ca4fe
Move RELEASENOTES content to a historic document as part of the
release-notes directory.
Also, rename Unreleased to Changes - the file includes both last release
and current unreleased changes.
Change-Id: Ia83609f53e4f7204a57b9fea6c356e9bdf7e5340
Some projects using openstackdocstheme may wish to customise
the default bug title to be better suited to their needs.
This patch implements the ability to do so.
To define it, add the variable to html_context in the Sphinx
conf.py.
For example:
html_context = {"bug_title": 'Documentation bug', ...}
Change-Id: Id62debd50fe0499ace809dde626cd8a357dbf933
Hervé Beraud