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

.zuul.yaml

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

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.

README.rst

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

bindep.txt

@@ -1,5 +1,4 @@
 # This is a cross-platform list tracking distribution packages needed by tests;
 # see http://docs.openstack.org/infra/bindep/ for additional information.
 
-python-sphinx [platform:dpkg]
-python-oslosphinx [platform:dpkg]
+tox [platform:dpkg]

doc/requirements.txt

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

doc/source/conf.py

@@ -22,10 +22,15 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinxcontrib.rsvgconverter',
     #'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
 # text edit cycles.
 # 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
 # Sphinx are currently 'default' and 'sphinxdoc'.
 # html_theme_path = ["."]
-# html_theme = '_theme'
+html_theme = 'openstackdocs'
 # html_static_path = ['static']
 
 # Output file base name for HTML help builder.
@@ -66,10 +71,15 @@ htmlhelp_basename = '%sdoc' % project
 # [howto/manual]).
 latex_documents = [
     ('index',
-     '%s.tex' % project,
-     u'%s Documentation' % project,
+     'doc-%s.tex' % project,
+     u'Eslint-config-openstack Documentation',
      u'OpenStack Foundation', 'manual'),
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
+
+latex_use_xindy = False
+latex_elements = {
+    'extraclassoptions': 'openany,oneside',
+}

doc/source/contributing.rst

@@ -10,9 +10,6 @@ project, the following will help get you started.
 Contributor License Agreement
 -----------------------------
 
-.. index::
-   single: license; agreement
-
 In order to contribute to the project, you need to have
 signed OpenStack's contributor's agreement.
 

doc/source/installation.rst

@@ -8,7 +8,8 @@ To add these rules to your project, follow these steps.
 
 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.

doc/source/readme.rst

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

package.json

@@ -15,7 +15,7 @@
   "scripts": {
     "test": "jasmine",
     "lint": "eslint ./",
-    "docs": "cd ./doc && make html"
+    "docs": "tox -e docs"
   },
   "repository": {
     "type": "git",

tox.ini

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