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.
    - The /doc folder did not contain requirements.txt file.

This patch fixes the above-mentioned problems and makes sure that
the documentation is generated properly.

Change-Id: I921b15edda433c3e47456488da6d2bda07c34262
Task: 35462

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.

doc/requirements.txt

@@ -0,0 +1,5 @@
+# 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.1 # Apache-2.0
+sphinx>=2.0.0,!=2.1.0 # BSD

doc/source/conf.py

@@ -23,7 +23,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
-    'oslosphinx'
+    'openstackdocstheme'
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -55,7 +55,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.
@@ -67,9 +67,14 @@ htmlhelp_basename = '%sdoc' % project
 latex_documents = [
     ('index',
      '%s.tex' % project,
-     u'%s Documentation' % 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