Fix building of the pdf documentation
The .pdf documentation could not be build without errors because the source code of the documentation contained errors. In addition, there were other problems: - The readme section of the documentation was in .md format instead of .rst format. As a result, the created documentation did not look good. - The .html documentation used deprecated oslosphinx theme instead of openstackdocstheme. This patch fixes the above-mentioned problems and makes sure that the documentation is generated properly. Also, this patch updates nodejs4-docs to nodejs10-docs because the nodejs4-docs was using deprecated nodejs-npm-run-docs job [1]. [1] https://review.opendev.org/c/openstack/openstack-zuul-jobs/+/757101 Task: 35462 Depends-On: I738b833109e4caeb58bb391d79d6e63284462bd8 Change-Id: I921b15edda433c3e47456488da6d2bda07c34262
This commit is contained in:
parent
6f6fa9f2f8
commit
3c9bc333ed
|
@ -1,4 +1,4 @@
|
||||||
- project:
|
- project:
|
||||||
templates:
|
templates:
|
||||||
- nodejs4-jobs
|
- nodejs4-jobs
|
||||||
- nodejs4-docs
|
- nodejs10-docs
|
||||||
|
|
40
README.md
40
README.md
|
@ -1,40 +0,0 @@
|
||||||
# eslint-config-openstack
|
|
||||||
|
|
||||||
OpenStack has a set of style guidelines for clarity. OpenStack is a very large code base, spanning
|
|
||||||
dozens of git trees, with over a thousand developers contributing every 6 months. As such, common
|
|
||||||
style helps developers understand code in reviews, move between projects smoothly, and overall make
|
|
||||||
the code more maintainable.
|
|
||||||
|
|
||||||
Even though eslint permits overriding rules on a per-project basis, it should be the goal of every
|
|
||||||
project to stay as close to the common guidelines as possible.
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
To add these rules to your project, follow these steps.
|
|
||||||
|
|
||||||
1. `npm install --save-dev eslint eslint-config-openstack`
|
|
||||||
2. Add `extends: "openstack"` to your `.eslintrc` yaml file. If your project is using ES2015, add
|
|
||||||
`extends: "openstack/es2015"` instead.
|
|
||||||
|
|
||||||
## Approval Policies
|
|
||||||
|
|
||||||
If you would like to contribute, please follow [OpenStack's contribution guidelines](https://wiki.openstack.org/wiki/How_To_Contribute).
|
|
||||||
|
|
||||||
|
|
||||||
#### Rules only land with consensus
|
|
||||||
Patches that activate, deactivate, or modify rules, should only be merged if a consensus of
|
|
||||||
reviewers is reached. In this case, consensus means at least five positive votes (+1 or +2),
|
|
||||||
with no -1 votes. Cores may not override and/or ignore -1 votes.
|
|
||||||
|
|
||||||
#### Library upgrades require two cores
|
|
||||||
Patches that upgrade eslint only require two core approvers to land. These patches must add new
|
|
||||||
upstream rules in a deactivated state, and delete any deprecated rules.
|
|
||||||
|
|
||||||
#### Policy upgrades require all cores
|
|
||||||
Updates to policies and governance on this project require +2 votes from all direct cores on the
|
|
||||||
project. Core votes from the parent OpenStack QA project are optional.
|
|
||||||
|
|
||||||
#### Patches should be abandoned after a month of inactivity
|
|
||||||
Cores should attempt to keep the list of extant patches small and managable. As such, they should
|
|
||||||
talk to any author whose patch has failed to garner the necessary support, and has experienced
|
|
||||||
one month of inactivity. Reasonable notice should be given to the author before a patch is
|
|
||||||
abandoned.
|
|
|
@ -0,0 +1,60 @@
|
||||||
|
.. _readme:
|
||||||
|
|
||||||
|
eslint-config-openstack
|
||||||
|
=======================
|
||||||
|
|
||||||
|
OpenStack has a set of style guidelines for clarity. OpenStack is a very
|
||||||
|
large code base, spanning dozens of git trees, with over a thousand
|
||||||
|
developers contributing every 6 months. As such, common style helps
|
||||||
|
developers understand code in reviews, move between projects smoothly,
|
||||||
|
and overall make the code more maintainable.
|
||||||
|
|
||||||
|
Even though eslint permits overriding rules on a per-project basis, it
|
||||||
|
should be the goal of every project to stay as close to the common
|
||||||
|
guidelines as possible.
|
||||||
|
|
||||||
|
Installation
|
||||||
|
------------
|
||||||
|
|
||||||
|
To add these rules to your project, follow these steps.
|
||||||
|
|
||||||
|
1. ``npm install --save-dev eslint eslint-config-openstack``
|
||||||
|
2. Add ``extends: "openstack"`` to your ``.eslintrc`` yaml file. If your
|
||||||
|
project is using ES2015, add ``extends: "openstack/es2015"`` instead.
|
||||||
|
|
||||||
|
Approval Policies
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
If you would like to contribute, please follow `OpenStack's contribution
|
||||||
|
guidelines <https://wiki.openstack.org/wiki/How_To_Contribute>`__.
|
||||||
|
|
||||||
|
Rules only land with consensus
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Patches that activate, deactivate, or modify rules, should only be
|
||||||
|
merged if a consensus of reviewers is reached. In this case, consensus
|
||||||
|
means at least five positive votes (+1 or +2), with no -1 votes. Cores
|
||||||
|
may not override and/or ignore -1 votes.
|
||||||
|
|
||||||
|
Library upgrades require two cores
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Patches that upgrade eslint only require two core approvers to land.
|
||||||
|
These patches must add new upstream rules in a deactivated state, and
|
||||||
|
delete any deprecated rules.
|
||||||
|
|
||||||
|
Policy upgrades require all cores
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Updates to policies and governance on this project require +2 votes from
|
||||||
|
all direct cores on the project. Core votes from the parent OpenStack QA
|
||||||
|
project are optional.
|
||||||
|
|
||||||
|
Patches should be abandoned after a month of inactivity
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Cores should attempt to keep the list of extant patches small and
|
||||||
|
managable. As such, they should talk to any author whose patch has
|
||||||
|
failed to garner the necessary support, and has experienced one month of
|
||||||
|
inactivity. Reasonable notice should be given to the author before a
|
||||||
|
patch is abandoned.
|
|
@ -1,5 +1,4 @@
|
||||||
# This is a cross-platform list tracking distribution packages needed by tests;
|
# This is a cross-platform list tracking distribution packages needed by tests;
|
||||||
# see http://docs.openstack.org/infra/bindep/ for additional information.
|
# see http://docs.openstack.org/infra/bindep/ for additional information.
|
||||||
|
|
||||||
python-sphinx [platform:dpkg]
|
tox [platform:dpkg]
|
||||||
python-oslosphinx [platform:dpkg]
|
|
||||||
|
|
|
@ -0,0 +1,8 @@
|
||||||
|
# The order of packages is significant, because pip processes them in the order
|
||||||
|
# of appearance. Changing the order has an impact on the overall integration
|
||||||
|
# process, which may cause wedges in the gate later.
|
||||||
|
|
||||||
|
openstackdocstheme>=2.2.0 # Apache-2.0
|
||||||
|
sphinx>=2.0.0,!=2.1.0 # BSD
|
||||||
|
sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
|
||||||
|
|
|
@ -22,10 +22,15 @@ sys.path.insert(0, os.path.abspath('../..'))
|
||||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||||
extensions = [
|
extensions = [
|
||||||
'sphinx.ext.autodoc',
|
'sphinx.ext.autodoc',
|
||||||
|
'sphinxcontrib.rsvgconverter',
|
||||||
#'sphinx.ext.intersphinx',
|
#'sphinx.ext.intersphinx',
|
||||||
'oslosphinx'
|
'openstackdocstheme'
|
||||||
]
|
]
|
||||||
|
|
||||||
|
# openstackdocstheme options
|
||||||
|
openstackdocs_repo_name = 'openstack/eslint-config-openstack'
|
||||||
|
openstackdocs_pdf_link = True
|
||||||
|
|
||||||
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
||||||
# text edit cycles.
|
# text edit cycles.
|
||||||
# execute "export SPHINX_DEBUG=1" in your terminal to disable
|
# execute "export SPHINX_DEBUG=1" in your terminal to disable
|
||||||
|
@ -55,7 +60,7 @@ pygments_style = 'sphinx'
|
||||||
# The theme to use for HTML and HTML Help pages. Major themes that come with
|
# The theme to use for HTML and HTML Help pages. Major themes that come with
|
||||||
# Sphinx are currently 'default' and 'sphinxdoc'.
|
# Sphinx are currently 'default' and 'sphinxdoc'.
|
||||||
# html_theme_path = ["."]
|
# html_theme_path = ["."]
|
||||||
# html_theme = '_theme'
|
html_theme = 'openstackdocs'
|
||||||
# html_static_path = ['static']
|
# html_static_path = ['static']
|
||||||
|
|
||||||
# Output file base name for HTML help builder.
|
# Output file base name for HTML help builder.
|
||||||
|
@ -66,10 +71,15 @@ htmlhelp_basename = '%sdoc' % project
|
||||||
# [howto/manual]).
|
# [howto/manual]).
|
||||||
latex_documents = [
|
latex_documents = [
|
||||||
('index',
|
('index',
|
||||||
'%s.tex' % project,
|
'doc-%s.tex' % project,
|
||||||
u'%s Documentation' % project,
|
u'Eslint-config-openstack Documentation',
|
||||||
u'OpenStack Foundation', 'manual'),
|
u'OpenStack Foundation', 'manual'),
|
||||||
]
|
]
|
||||||
|
|
||||||
# Example configuration for intersphinx: refer to the Python standard library.
|
# Example configuration for intersphinx: refer to the Python standard library.
|
||||||
#intersphinx_mapping = {'http://docs.python.org/': None}
|
#intersphinx_mapping = {'http://docs.python.org/': None}
|
||||||
|
|
||||||
|
latex_use_xindy = False
|
||||||
|
latex_elements = {
|
||||||
|
'extraclassoptions': 'openany,oneside',
|
||||||
|
}
|
||||||
|
|
|
@ -10,9 +10,6 @@ project, the following will help get you started.
|
||||||
Contributor License Agreement
|
Contributor License Agreement
|
||||||
-----------------------------
|
-----------------------------
|
||||||
|
|
||||||
.. index::
|
|
||||||
single: license; agreement
|
|
||||||
|
|
||||||
In order to contribute to the project, you need to have
|
In order to contribute to the project, you need to have
|
||||||
signed OpenStack's contributor's agreement.
|
signed OpenStack's contributor's agreement.
|
||||||
|
|
||||||
|
|
|
@ -8,7 +8,8 @@ To add these rules to your project, follow these steps.
|
||||||
|
|
||||||
1. Install the npm package to your project:
|
1. Install the npm package to your project:
|
||||||
|
|
||||||
`npm install --save-dev eslint eslint-config-openstack`
|
``npm install --save-dev eslint eslint-config-openstack``
|
||||||
|
|
||||||
|
2. Add ``extends: "openstack"`` to your ``.eslintrc`` yaml file.
|
||||||
|
If your project is using ES2015, add ``extends: "openstack/es2015"`` instead.
|
||||||
|
|
||||||
2. Add `extends: "openstack"` to your `.eslintrc` yaml file.
|
|
||||||
If your project is using ES2015, add `extends: "openstack/es2015"` instead.
|
|
||||||
|
|
|
@ -0,0 +1 @@
|
||||||
|
.. include:: ../../README.rst
|
|
@ -15,7 +15,7 @@
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"test": "jasmine",
|
"test": "jasmine",
|
||||||
"lint": "eslint ./",
|
"lint": "eslint ./",
|
||||||
"docs": "cd ./doc && make html"
|
"docs": "tox -e docs"
|
||||||
},
|
},
|
||||||
"repository": {
|
"repository": {
|
||||||
"type": "git",
|
"type": "git",
|
||||||
|
|
|
@ -0,0 +1,32 @@
|
||||||
|
[tox]
|
||||||
|
minversion = 2.4.0
|
||||||
|
skipsdist = True
|
||||||
|
ignore_basepython_conflict = True
|
||||||
|
|
||||||
|
[testenv]
|
||||||
|
basepython = python3
|
||||||
|
setenv =
|
||||||
|
VIRTUAL_ENV={envdir}
|
||||||
|
OS_LOG_CAPTURE=1
|
||||||
|
OS_STDOUT_CAPTURE=1
|
||||||
|
OS_STDERR_CAPTURE=1
|
||||||
|
OS_TEST_TIMEOUT=160
|
||||||
|
PYTHONWARNINGS=default::DeprecationWarning,ignore::DeprecationWarning:distutils,ignore::DeprecationWarning:site
|
||||||
|
|
||||||
|
[testenv:docs]
|
||||||
|
deps =
|
||||||
|
-c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
|
||||||
|
-r{toxinidir}/doc/requirements.txt
|
||||||
|
commands =
|
||||||
|
rm -rf doc/build
|
||||||
|
sphinx-build -W -b html doc/source doc/build/html
|
||||||
|
whitelist_externals = rm
|
||||||
|
|
||||||
|
[testenv:pdf-docs]
|
||||||
|
deps = {[testenv:docs]deps}
|
||||||
|
whitelist_externals =
|
||||||
|
make
|
||||||
|
commands =
|
||||||
|
sphinx-build -W -b latex doc/source doc/build/pdf
|
||||||
|
make -C doc/build/pdf
|
||||||
|
|
Loading…
Reference in New Issue