Commit Graph

100 Commits

Author SHA1 Message Date
Andreas Jaeger d3cdb8689b Change name of OpenStack Foundation
OpenStack Foundation got renamed to Open Infrastructure Foundation,
follow the rename and update links as well.

Remove no longer working links.

Change-Id: Iee3bb16fb6554ad80a3263f4f364976bcb8c88e1
2020-10-22 09:51:36 +02:00
Hervé Beraud ff156664e6 Adding pre-commit
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>
2020-09-15 14:46:10 +02:00
Andreas Jaeger e974da0a35 Add link to PDF file
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
2020-05-18 14:58:31 +02:00
Andreas Jaeger 78dc56d979 Update docstheme
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
2020-05-15 08:50:51 +02:00
Stephen Finucane 7ad72dc84a Add package prefixes for all config options
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>
2020-05-13 14:32:20 +00:00
Stephen Finucane 2b258f0380 Merge, rather than overwrite, LaTeX settings
This leads to more predictable behavior.

Change-Id: I3a9d96c4896a0d5ccc85b74562d35852a837f29f
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Closes-Bug: #1843527
2020-04-24 13:46:03 +01:00
Stephen Finucane 1246a46deb Add 'openstackdocs_auto_name' config option
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>
2020-04-24 13:46:00 +01:00
Stephen Finucane 2b2e4e50b6 Add 'openstackdocs_auto_version' config option, path checking
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
2020-04-24 12:04:21 +01:00
Akihiro Motoki 3e97737e5a Fetch generated PDF files correctly
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
2019-09-18 09:51:07 +09:00
chenxing d32531868b Note External Link Helper is not compatible with project only master brach
Change-Id: I386f3d81ebf496b8ddac55fd801b1cab68680fbf
2019-05-30 15:17:33 +08:00
Stephen Finucane e137ed4f35 Add table styling
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
2019-05-24 18:27:09 +01:00
Andreas Jaeger 2d76fd9cff Update for OpenDev change
Use the new OpenDev URLs everywhere, follow move of repositories.

Change-Id: I3dd8c6deff91c4cc3b8958977e73f371bdeb82a0
2019-04-21 14:27:39 +00:00
Andreas Jaeger 98c23d2b84 Fix typo
s/diplayed/displayed/

Change-Id: Idd22343b2b204b1cfc4c911036e7ecfb6d5c8321
2018-11-05 21:15:55 +01:00
Sean McGinnis 4878259826 Remove example of deprecated app.info
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>
2018-10-15 10:55:11 -05:00
Dean Troyer b0166265a8 Add starlingxdocs theme support
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>
2018-10-05 06:32:51 +00:00
Thierry Carrez c3bf0d1f62 Add an option to disable global TOC section
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
2018-09-26 15:25:45 +02:00
Thierry Carrez 034683f12d Make root title customizable
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
2018-09-26 15:24:41 +02:00
chenxing c7f1ed0028 Fix the incorrect storyboard url
Using "repository_name" instead of "bug_project" to combine with the
"urlBase" string, if set use_storyboard to "True". storyboard URLs are
in this format:
"https://storyboard.openstack.org/#!/project/"+"openstack/whereto"
not:
"https://storyboard.openstack.org/#!/project/"+"whereto"

Change-Id: Ib553d95f22c7848a5bd537b8929a2d6e6625451b
2018-09-13 08:51:44 +08:00
Andreas Jaeger fde94a8a86 Fix use_storyboard
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
2018-09-04 21:13:59 +02:00
Zuul 344b423e01 Merge "Handle StoryBoard project groups" 2018-08-24 03:21:02 +00:00
Andreas Jaeger 038a8f712d Handle StoryBoard project groups
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
2018-08-23 21:10:03 +02:00
Andreas Jaeger e72301e141 Do not show badge for master only repos
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
2018-08-23 20:36:57 +02:00
Andreas Jaeger 8715f67645 Do not display "latest" badge if repo is not versioned
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
2018-08-18 15:40:41 +02:00
Stephen Finucane 3c8b2a6988 Configure additional properties
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
2018-03-13 16:51:41 +00:00
Stephen Finucane d03cea1f34 Configure project name, version, release
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
2018-03-13 16:49:25 +00:00
Stephen Finucane 191502db2a trivial: Remove cruft from 'conf.py'
This serves as a reference guide of sorts. No need to keep all the noise
around.

Change-Id: Id9a636a4e4d7586ad395e2a2eb00b3bc08c61fa2
2018-03-12 16:46:52 +00:00
Stephen Finucane df389787cd trivial: Generate '{project}-doc' roles, not '{project}-doc-link'
The latter are overly verbose, while the former have a natural synergy
with the 'doc' role provided by Sphinx.

Change-Id: Ib2fd91c1115270d3eb7d8197efdf4b5e8a7316a9
2018-02-05 15:32:43 +00:00
Doug Hellmann 1bde61037c automatically create project doc-link roles
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>
2018-01-25 11:04:20 -05:00
Stephen Finucane 62c8f36d93 Revert "Fix the incorrect git source url"
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
2018-01-09 16:47:33 +00:00
chenxing f0744a1675 Fix the incorrect git source url
Documentation not located in 'doc/source' directory needs the
giturl value to make the source url correct.

Change-Id: I772a66de4680ba73ed79f8ea5481d6900f71fa82
Closes-Bug: #1732630
2018-01-08 15:07:13 +08:00
OpenStack Proposal Bot 75586c700b Updated from global requirements
Change-Id: I538b974a2b7b64c492a4c852d874296d891d28a6
2017-12-03 21:36:45 +00:00
Andreas Jaeger 95aa5e0dc5 Avoid tox_install.sh for constraints support
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
2017-11-30 22:00:06 +01:00
James E. Blair a17640aab6 Add support for sphinx sidebar role
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
2017-08-31 08:13:03 -07:00
James E. Blair 5c1714c234 Remove stray characters from demo
These appear to have been confusing sphinx, which caused test jobs
to fail since we treat sphinx warnings as errors.

Change-Id: I75c52c3451ab130e50da7ab3537eac7ca12ccf74
2017-08-31 07:56:49 -07:00
chenxing af471ca940 Update the configuration of generating a PDF document
Change-Id: Ib02619173fb60ae834562ef54df6118f8390fc4a
Closes-Bug: #1712726
2017-08-24 12:21:57 +08:00
Jenkins 8fffae6be5 Merge "Documents how to set conf.py for PDF generation" 2017-08-03 14:36:49 +00:00
Ian Y. Choi de9b58904e Documents how to set conf.py for PDF generation
It is a good idea to describe which things are needed
for PDF generation using openstackdocstheme.

Change-Id: I343c1fb5853da396f4de28a5e9b236195dcd5f4d
2017-07-31 16:22:29 +00:00
Doug Hellmann 2e8624f445 show release series names not version tags
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>
2017-07-31 11:30:49 -04:00
Rob Cresswell 979785c760 Fix a logic issue in the JS
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
2017-07-26 12:55:24 +01:00
Doug Hellmann 9664113d83 move the localtoc for the page into the sidebar
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>
2017-07-25 11:27:54 -04:00
Jenkins d602fa119b Merge "Fix Added / Changed / Deprecated notices" 2017-07-24 16:53:56 +00:00
Hangdong Zhang 8ae163ace8 Update 2 documentation URLs according to doc migration
Change-Id: I195b901e570b977413ca10cf40da054c9f45bb99
2017-07-24 17:13:26 +08:00
Rob Cresswell a0592b58fd Fix Added / Changed / Deprecated notices
Change-Id: Ida45dc821098446fae9b03ff68d28a675c1ca9c7
2017-07-21 06:44:52 +00:00
Andreas Jaeger 560d98ace9 Add spaces in demo for deprecation notices
There should be a space before an "(".

Change-Id: I6a69ff84aab51711af7656b7186fadd023e652d2
2017-07-16 09:45:08 +02:00
Rob Cresswell 2969174191 Add support for versionadded and deprecated
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
2017-07-11 10:24:52 +00:00
Andreas Jaeger ab2b99c978 Cleanup conf.py
Adapt for current theme options, remove obsolete code.

Change-Id: I900fa3914463147acaf40e81f54f2f80abcac048
2017-07-04 13:47:08 +02:00
Andreas Jaeger cb33fecb2d Add note for show_other_versions
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
2017-07-03 19:29:42 +02:00
Jenkins 47e20ca671 Merge "Update docs" 2017-06-30 17:59:03 +00:00
Jenkins b5e31dc5f0 Merge "Increase admonition.important contrast" 2017-06-30 17:58:12 +00:00
James E. Blair 1d54ae62b4 Increase admonition.important contrast
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
2017-06-30 17:07:26 +00:00