Commit Graph

44 Commits

Author SHA1 Message Date
Radomir Dopieralski 80f1e30902 Fix sphinx extlinks captions
We are hitting https://github.com/sphinx-doc/sphinx/issues/11094 due
to changes in Sphinx.

Change-Id: Ie2d271c8cfbccd21aae1902ede49ac22321a67c6
2023-08-30 10:35:46 +02:00
YuehuiLei 87f498bee5 Drop the usage of unicode prefix from unicode strings
All strings are considered as unicode strings in python 3,
so we no longer need "u" prefix (u'...').

Co-Authored-By: Akihiro Motoki <amotoki@gmail.com>
Change-Id: I796d2fcdca066475bbf29d25cbf2aa67b2b2178b
2021-02-12 13:05:27 -06:00
Hervé Beraud 17d8ab6103 Stop to use the __future__ module.
The __future__ module [1] was used in this context to ensure compatibility
between python 2 and python 3.

We previously dropped the support of python 2.7 [2] and now we only support
python 3 so we don't need to continue to use this module and the imports
listed below.

Imports commonly used and their related PEPs:
- `division` is related to PEP 238 [3]
- `print_function` is related to PEP 3105 [4]
- `unicode_literals` is related to PEP 3112 [5]
- `with_statement` is related to PEP 343 [6]
- `absolute_import` is related to PEP 328 [7]

[1] https://docs.python.org/3/library/__future__.html
[2] https://governance.openstack.org/tc/goals/selected/ussuri/drop-py27.html
[3] https://www.python.org/dev/peps/pep-0238
[4] https://www.python.org/dev/peps/pep-3105
[5] https://www.python.org/dev/peps/pep-3112
[6] https://www.python.org/dev/peps/pep-0343
[7] https://www.python.org/dev/peps/pep-0328

Change-Id: Ic03754dcaaa4f1c0018294aa52bb05d956aa5d10
2020-06-03 10:45:18 +02:00
Andreas Jaeger c377c02740 Fix published docs
Change I90d064e63baa5f067f38a881eb9a556dfb435e97 contained a few typos
which broke the PDF and "Report a bug" icons on
https://docs.openstack.org/horizon/latest/ .

Fix the typos.

Change pygments_style to 'native' since old theme version always used
'native' and the theme now respects the setting and using 'sphinx' can
lead to some strange rendering.

Change-Id: Iab18f322331f13f85f64fb4730d276b9d351b8cc
2020-05-22 14:36:29 +02:00
manchandavishal f8658d9880 Switch to newer openstackdocstheme and reno versions
Switch to openstackdocstheme 2.2.0 and reno 3.1.0 versions. Using
these versions will allow especially:
* Linking from HTML to PDF document
* parallelizing building of documents

Update Sphinx version as well.

openstackdocstheme renames some variables, so follow the renames. A
couple of variables are also not needed anymore, remove them.

Set openstackdocs_pdf_link to link to PDF file.

Remove docs requirements from lower-constraints, they are not installed.

For more info. please refer [1].
[1] https://review.opendev.org/728938

Change-Id: I90d064e63baa5f067f38a881eb9a556dfb435e97
2020-05-19 15:26:39 +00:00
Akihiro Motoki 0a0fb835b8 PDF documentation build
Based on https://review.opendev.org/#/c/601659/ and
https://review.opendev.org/#/c/664555/

The generated PDF file is found at the top directory of the job log.

Story: 2006084
Task: 34864
Depends-On: https://review.opendev.org/664555
Change-Id: I5e25f1dfbec22b26d42eff3c6776a2d01e90bc60
2019-09-04 05:19:00 +00:00
pengyuesheng b529f00937 Bump the openstackdocstheme extension to 1.20
Some options are now automatically configured by the version 1.20:
- project
- html_last_updated_fmt
- latex_engine
- latex_elements
- version
- release.

This will shows the version selector of the doc, too.

Change-Id: I38f0385a1fd676a4ba18259af7ad384af31ebe5a
2019-07-02 14:07:14 +08:00
Akihiro Motoki 9790293c2a Update URLs of horizon plugin registry
As result of the recent opendev migration, github repositories
for non-TC-governed OpenStack projects are not synced automatically.
group-based-policy-ui is such repository.
It is a good chance to point repositories on opendev.org.
This commit replaces github links to opendev links.

This commit also updates bug tracker links to more direct links
to the bug trackers.

sphinx extlink is now used to simplify the plugin registry doc.

Change-Id: Ib1a746e2cd6c7ed0c81c10e2767d6f76ad0203b9
2019-05-23 22:16:22 +09:00
Akihiro Motoki 25b6706f50 Allow to run pep8/docs tox env with horizon plugins
As of now, when horizon plugins are configured in the horizon repo,
pep8 and docs tox env cannot run.
This is because openstack_dashboard.settings tries to load horizon plugins
but horizon plugins are not installed in tox env by default and
the jobs will fail as a result.
This commit changes to use openstack_dashboard.test.settings
as DJANGO_SETTINGS_MODULE for these tox environments by default.

Change-Id: I6a9d0c74271cc4addd8a0964b5955d7d3b6d8267
2018-12-23 02:34:38 +09:00
Akihiro Motoki f0f028ca35 Fix E402 warnings
E402 module level import not at top of file

Change-Id: Ia8425ffe5b1325d00ae482d99b6764fd0fcbf822
2018-04-11 18:57:28 +09:00
Akihiro Motoki eac3eae35a Follow the new PTI for document build
The detail is described in the following links:
https://governance.openstack.org/tc/reference/project-testing-interface.html
http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html

doc8 command is dropped from docs and releasenotes tox envs.
We run doc8 in pep8 tox env, so this hurts nothing.

Change-Id: I24271b527258b1de4cf26ca7efd625954eb834de
2018-03-25 02:14:40 +09:00
Akihiro Motoki e6b78f92f2 Use flake8-import-order plugin
In reviews we usually check import grouping but it is boring.
By using flake8-import-order plugin, we can avoid this.
This flake8 plugin is already used in tempest.
It enforces loose checking so it sounds good to use.

Note that flake8-import-order version is pinned to avoid unexpected
breakage of pep8 job.

Change-Id: I8ccd05eb70350a2441cc2a4d1eafc09ee690b83b
2017-07-03 08:02:23 +00:00
Doug Hellmann baa9b9c732 use openstackdocstheme html context
Set some of the new config values and enable openstackdocstheme as an
extension so it will inject values into the page context as it writes
each documentation page. This ensures the pages link to the right bug
tracker, etc.

Change-Id: I36d400358b1b5e2c2423c43f43c775bafb0d4721
Depends-On: Icf3a40ed104cfd828f532f6f2b112ed02f996ff5
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
2017-06-28 19:51:10 +09:00
Vu Cong Tuan 456e92dbe5 Fix html_last_updated_fmt for Python3
html_last_updated_fmt option is interpreted as a
byte string in python3, causing Sphinx build to break.
This patch makes it utf-8 string.

Changing Popen to .check_output because of 3 reasons:
1. check_output() will raise CalledProcessError if
the called process returns a non-zero return code.
2. For consistency with keystone [1] and cinder [2]
3. It makes the code look much better.

[1] https://review.openstack.org/#/c/457142/
[2] https://review.openstack.org/#/c/433081

Change-Id: Ia6721b3b2bdf8427e8c42b4f056f5fcb7c4b73ee
2017-06-12 09:33:39 +07:00
Rob Cresswell 6eb8394213 Update the quickstart guide
This patch is the first in a series improving Horizons documentation. It
aims to make the initial quick start section clearer, updates the
information to remove some redundant information, and updates the
appearance to match the rest of the openstack docs.

Change-Id: I942e62b6c2c272dc2b5c91bca42c77677bb4e09d
Implements: blueprint pike-docs-overhaul
2017-06-08 21:01:37 +01:00
Akihiro Motoki 117cec9b54 doc: Ignore warnings from dashboard build in the doc build
There is no need to catch warnings from openstack_dashboard.settings
in the doc build job. This might be a bug of a recent Sphinx 1.6.x,
but I think it is useful to have this setting to avoid unexpected failures.

Change-Id: I9894622ba0f5fbb74e9dac016ed76ac9e3c2f733
2017-06-01 02:41:36 +00:00
Akihiro Motoki 215ccba9ec doc: Do not generate no source code reference
horizon devref has both explicit autodoc directives and
automatically generated source references.
This causes a lot of 'WARNING: duplicate object description'.

I think that we don't need source code references for most modules
and it is better to have explicit API references of modules
for which we need references. Thus this commit removes the logic
to generate source references.

This contributes a lot to reduce the number of sphinx warnings.
Also reduces the required time of documentation build :-)

Partial-Bug: #1411719
Partial-Bug: #1486222
Change-Id: Iba2bf3723cad159f4cfd1fff47e8114d9867e040
2016-09-24 20:44:48 +09:00
Kaitlin Farr dbd907643f Fix doc build warnings and errors
This change addresses the warnings and errors that are displayed when the
docs are built, including:

 * Add reference to previously unreferenced workflow_extend in index file
 * Remove reference to a _static directory that doesn't exist
 * Fix formatting issues within the workflow_extend document

Comments in the bug report discuss the need for warnings to be treated
as errors, but this does not seem to be possible using the setup.py build_sphinx
command.

Change-Id: Iccccb9d104df9847ecd8a52aa73a7aa450bb5f34
Partial-Bug: #1411719
2016-05-17 18:53:03 -04:00
Thomas Bechtold 33b000a57d Fix doc build if git is absent
When building packages if git is absent, then we should not set
html_last_updated_fmt. It can still be set via the -D switch
when building with sphinx-build.

Change-Id: I905736fc5f998385128b306c75bc8191b2797dc6
Closes-Bug: #1552251
2016-04-13 09:46:35 +02:00
Jenkins 3666072654 Merge "Fixing the deprecated library function." 2016-04-05 05:34:34 +00:00
Jenkins 99edc5c613 Merge "Optimize "open" method with context manager" 2016-04-05 05:32:22 +00:00
Andreas Jaeger 7323abcc2a Remove unused pngmath Sphinx extension
There's no RST file that uses ".. math" and thus
the pngmath Sphinx extension is not used and can
get removed.

Change-Id: I3ea4b529025c8ac3c4092f3720124647861e6668
2016-02-28 20:46:19 +01:00
Harshada Mangesh Kakad 935c483b9e Fixing the deprecated library function.
os.popen() is deprecated since version 2.6. Resolved with use of
subprocess module.

Change-Id: I6ac6eb8618dd3d7325b43c67c1cb294bd8bff702
Partial-Bug: #1529836
2015-12-31 08:59:40 -08:00
xiexs c7c86ed22c Optimize "open" method with context manager
Use opening context manager to open a file.

Change-Id: Ib03c6b4d70f31178031124fe1ff99c6fbd0e3966
2015-11-27 04:14:11 -05:00
David Lyle 49ae7f9eeb Fix docs translation import errors
When building docs, there are a ton of errors in this format:

AppRegistryNotReady: The translation infrastructure cannot be
initialized before the apps registry is ready. Check that you don't make
non-lazy gettext calls at import time.

Starting in Django 1.7, standalone scripts, such as a sphinx build
require that django.setup() be called first. See:
https://docs.djangoproject.com/en/1.8/releases/1.7/#standalone-scripts

This should be added to the horizon/docs/source/conf.py

Doing so eliminates the errors.

Closes-Bug: #1486139
Change-Id: I0871be3d60d4d78cb430fabdb5725832559191d7
2015-08-18 14:14:41 -06:00
lin-hua-cheng 248115d6fd Fixes modules index generated by Sphinx
Sphinx was always using (h)orizon and (o)penstack_dashboard for the
prefix so the index wasn't very useful.

Change-Id: Ifbd86d8d12e6dd808646d3b0708ca98ec6428e26
2015-07-09 23:10:25 -07:00
Akihiro Motoki a25091e89f Update doc/source/conf.py
* Exclude test files from source code index
* Add an index to jump to sub indexes in source code index
* Ensure the order of source code index by using an array
  rather than a dict.

Change-Id: I5c28a3e29c9c0b0332732d3f598030a77536563a
2014-10-14 04:13:52 +09:00
Andreas Jaeger d9870c7e85 Stop using intersphinx
Remove intersphinx from the docs build as it triggers network calls that
occasionally fail, and we don't really use intersphinx (links other
sphinx documents out on the internet)

This also removes the requirement for internet access during docs build.

This causes docs jobs to fail because we error out on warnings.

Change-Id: I71e941e2a639641a662a163c682eb86d51de42fb
Related-Bug: #1368910
2014-09-12 22:38:24 +02:00
Akihiro Motoki cd35fff1b6 Re-enable flake8 check
This is the final fix to re-enable flake8/pep8 check in the gate.
E265 errors in doc/source/conf.py are also fixed.

Imports with "from xxxx import (xxxx)" style cannot pass "tox -e pep8"
though they pass "run_tests.sh -p". Newlines with backslash escape
is used in this commit to pass it.
The reason needs to be investigated later.

Change-Id: Ic0d765d404212d13f678b2a3aef7b9612bf5238d
Closes-Bug: #1347472
2014-07-31 04:16:36 +09:00
Gary W. Smith 1f38f87138 Fix keystone warnings while building docs
When building the documentation via run_tests.sh, doc/source/conf.py
explicitly sets the DJANGO_SETTINGS_MODULE environment variable,
overriding any existing value that it already has. Furthermore, it sets
it to point to a settings file that does not use keystone v3, which
is expected by the tests (and is the source of the warning).  Note that
when running unit tests via run_tests.sh, a different settings file is
supplied which DOES use keystone v3.

Change the doc/source/conf.py to only set DJANGO_SETTINGS_MODULE if it
is not already set.  Change tox.ini and run_tests.sh to set
DJANGO_SETTINGS_MODULE to the same settings file used by the unit tests,
with keystone v3 support.

Change-Id: Ib297e4188f2426cf575300998bc9d50f36e48f4f
Closes-Bug: #1257725
2014-06-16 15:42:18 -07:00
Jenkins 700dc59825 Merge "Use built-in print() instead of print statement" 2014-04-08 10:26:47 +00:00
ChenZheng 20c63e7e30 Use built-in print() instead of print statement
In python 3 print statement is not supported, so we should use
only print() functions.

Fixes bug 1226943

Change-Id: I721e67c917ba7018401ad40ef30081883dcec420
2014-03-24 16:28:55 +08:00
Cyril Roelandt 96df098bec Switch over to oslosphinx
oslosphinx is the new name of oslo.sphinx

Closes-Bug: #1277168
Change-Id: I4cebcffb36724d699147a26eb1132b122cfe669c
2014-03-21 15:23:44 +01:00
Paul Belanger 74117eb8b6 Gate on H102 Apache 2.0 license header not found for pep8
Now all files are properly licensed per OpenStack Hacking.

Change-Id: I223d983018568357197b0d9cf5dde12c135c53c9
Signed-off-by: Paul Belanger <paul.belanger@polybeacon.com>
2013-11-19 13:55:04 -05:00
ZhiQiang Fan 686cc88fd2 Replace OpenStack LLC with OpenStack Foundation
Change-Id: I6c638f04fb7c97ac986ef31c1190011ed90a43d2
Fixes-Bug: #1214176
2013-09-20 04:19:42 +08:00
Doug Hellmann b6f7d8318b Use oslo.sphinx and remove local copy of doc theme
Use the new oslo.sphinx version of the OpenStack doc
theme instead of copying it into this repo.

blueprint oslo.sphinx

Signed-off-by: Doug Hellmann <doug.hellmann@dreamhost.com>
Change-Id: I0bd91f7bb43f97b99051fed65b75fc05d5149cc8
2013-07-05 16:10:43 -04:00
Monty Taylor 7643f52fb2 Move to flake8.
The project is standardizing on flake8 for static code analysis.

Change-Id: I4fd97b56b6c6cb57e8d245281e0da15f838ec840
2013-05-01 10:32:14 -04:00
Monty Taylor 11867173ed Update to latest oslo-version.
In preparation for tag-based versions, update to latest oslo-version code.

Change-Id: I9f702f0304fdd5043326c95346b26bde06e20a1e
2013-02-04 11:28:25 +11:00
Ray Chen b177299953 PEP8 issues fixed
Fix some PEP8 issues in file doc/source/conf.py to make the code more
pretty.

Change-Id: I2efdb39c8991bf0cae180f7c4ffd459f6b418fc5
2012-08-23 15:44:16 +08:00
Matt Joyce ac2b355229 grammar fixes and other minutia
Change-Id: I48d4fa3dddd199ad4c66a6ee8a73bbaeff08fa62
2012-08-22 14:14:37 -07:00
Clark Boylan f1a8e0c54f Move docs to doc.
To better facilitate the building and publishing of sphinx
documentation by Jenkins we are moving all openstack projects with
sphinx documentation to a common doc tree structure. Documentation
goes in project/doc and build results go in project/doc/build.

Change-Id: Ic523a716e4113198b777d6dc3db8bb8a729e7696
2012-06-12 11:41:04 -07:00
Gabriel Hurley 9742842795 Re-architects the OpenStack Dashboard for modularity and extensibility.
Implements blueprint extensible-architecture.
Implements blueprint improve-dev-documentation.
Implements blueprint gettext-everywhere.
Implements blueprint sphinx-docs.

Complete re-architecture of the dashboard to transform it from a standalone django-openstack app to a Horizon framework for building dashboards. See the docs for more information.

Incidentally fixes the following bugs:

Fixes bug 845868 -- no PEP8 violations.
Fixes bug 766096 -- the dashboard can now be installed at any arbitrary URL.
Fixes bug 879111 -- tenant id is now controlled solely by the tenant switcher, not the url (which was disregarded anyway)
Fixes bug 794754 -- output of venv installation is considerably reduced.

Due to the scale and scope of this patch I recommend reviewing it on github: https://github.com/gabrielhurley/horizon/tree/extensible_architecture

Change-Id: I8e63f7ea235f904247df40c33cb66338d973df9e
2011-11-07 12:59:21 -08:00
Joe Heck 6e7d208436 adding version to project, setting up autobuild of docs with ./run_tests.sh --docs 2011-10-27 13:23:39 -07:00
Joe Heck 7fbd04358d adding developer docs 2011-10-27 13:23:39 -07:00