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:
Lukas Piwowarski 2020-09-10 15:57:50 +02:00
parent 6f6fa9f2f8
commit 3c9bc333ed
11 changed files with 122 additions and 54 deletions

View File

@ -1,4 +1,4 @@
- project: - project:
templates: templates:
- nodejs4-jobs - nodejs4-jobs
- nodejs4-docs - nodejs10-docs

View File

@ -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.

60
README.rst Normal file
View File

@ -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.

View File

@ -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]

8
doc/requirements.txt Normal file
View File

@ -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

View File

@ -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',
}

View File

@ -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.

View File

@ -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.

1
doc/source/readme.rst Normal file
View File

@ -0,0 +1 @@
.. include:: ../../README.rst

View File

@ -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",

32
tox.ini Normal file
View File

@ -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