Add support for PDF doc generation

This adds support for pdf documentation generation. Work items:

* Provide a distinct index for pdf doc. This is required as the toctree in a
  tab fails to render as a pdf document.

* Remove the v2 API reference from the pdf documentation. "rest_expand_all",
  "rest_method" and "rest_parameters" are not supported.

* Add a pdf-docs tox env

* Update conf.py

Story: 2006075
Task: 34808
Change-Id: I848d59b551fe6d5077960dc45554c7281c2372a7

doc/source/api-reference/index.rst

@@ -13,11 +13,14 @@ API v1
    v1/*
    v1/rating/*
 
-API v2
+.. only:: html
-======
 
-.. toctree::
+   API v2
-   :maxdepth: 2
+   ======
-   :glob:
 
-   v2/*
+
+   .. toctree::
+      :maxdepth: 2
+      :glob:
+
+      v2/*

doc/source/common-index.rst

@@ -0,0 +1,59 @@
+What is CloudKitty ?
+====================
+
+CloudKitty is a **Rating-as-a-Service** project for OpenStack and more.
+The project aims at being a **generic** solution for the chargeback and rating
+of a cloud. Historically, it was only possible to operate it inside of an
+OpenStack context, but it is now possible to run CloudKitty in standalone mode.
+
+CloudKitty allows to do metric-based rating: it polls endpoints in order to
+retrieve measures and metadata about specific metrics, applies rating rules to
+the collected data and pushes the rated data to its storage backend.
+
+CloudKitty is highly modular, which makes it easy to add new features.
+
+.. only:: html
+
+   .. note::
+
+      **We're looking for contributors!** If you want to contribute, please have
+      a look at the `developer documentation`_ .
+
+.. _developer documentation: developer/index.html
+
+What can be done with CloudKitty ? What can't ?
+===============================================
+
+**With Cloudkitty, it is possible to:**
+
+- Collect metrics from OpenStack (through Gnocchi and Monasca) or from
+  somewhere else (through Gnocchi in standalone mode and Prometheus). Metric
+  collection is **highly customizable**.
+
+- Apply rating rules to the previous metrics through the `hashmap`_ module or
+  `custom scripts`_. This is all done via CloudKitty's API.
+
+- Retrieve the rated information through the API, grouped by scope and/or by
+  metric type.
+
+**However, it is not possible to:**
+
+- Limit resources in other OpenStack services once a certain limit has been
+  reached. Ex: block instance creation in Nova above a certain price.
+  Cloudkitty does **rating and only rating**.
+
+- Add taxes, convert between currencies, etc... This needs to be done by a
+  billing software. CloudKitty associates a price to a metric for a given
+  period, but the price's unit is what you decide it to be: euros, dollars,
+  cents, squirrels...
+
+.. _custom scripts: user/rating/pyscripts.html
+
+.. _roadmap: developer/roadmap.html
+
+What changes/features are to expect ?
+=====================================
+
+If you're interested in CloudKitty's evolution, see the project's `roadmap`_ .
+
+.. _hashmap: user/rating/hashmap.html

doc/source/conf.py

@@ -226,7 +226,7 @@ htmlhelp_basename = 'cloudkittydoc'
 # (source start file, target name, title, author,
 # documentclass [howto/manual]).
 latex_documents = [
-    ('index', 'Cloudkitty.tex', u'Cloudkitty Documentation',
+    ('pdf-index', 'doc-cloudkitty.tex', u'Cloudkitty Documentation',
      u'Cloudkitty Team', 'manual'),
 ]
 
@@ -246,3 +246,15 @@ latex_documents = [
 
 # If false, no module index is generated.
 #latex_use_modindex = True
+
+# If false, no module index is generated.
+latex_domain_indices = False
+
+latex_elements = {
+    'makeindex': '',
+    'printindex': '',
+    'preamble': r'\setcounter{tocdepth}{3}',
+}
+
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+latex_use_xindy = False

doc/source/index.rst

@@ -2,63 +2,11 @@
 Welcome to CloudKitty's documentation!
 ======================================
 
-What is CloudKitty ?
+..
-====================
+   NOTE: This is the index for the rst version only. If you update this file
+   please update pdf-index.rst accordingly
 
-CloudKitty is a **Rating-as-a-Service** project for OpenStack and more.
+.. include:: common-index.rst
-The project aims at being a **generic** solution for the chargeback and rating
-of a cloud. Historically, it was only possible to operate it inside of an
-OpenStack context, but it is now possible to run CloudKitty in standalone mode.
-
-CloudKitty allows to do metric-based rating: it polls endpoints in order to
-retrieve measures and metadata about specific metrics, applies rating rules to
-the collected data and pushes the rated data to its storage backend.
-
-CloudKitty is highly modular, which makes it easy to add new features.
-
-.. note::
-
-   **We're looking for contributors!** If you want to contribute, please have
-   a look at the `developer documentation`_ .
-
-.. _developer documentation: developer/index.html
-
-What can be done with CloudKitty ? What can't ?
-===============================================
-
-**With Cloudkitty, it is possible to:**
-
-- Collect metrics from OpenStack (through Gnocchi and Monasca) or from
-  somewhere else (through Gnocchi in standalone mode and Prometheus). Metric
-  collection is **highly customizable**.
-
-- Apply rating rules to the previous metrics through the `hashmap`_ module or
-  `custom scripts`_. This is all done via CloudKitty's API.
-
-- Retrieve the rated information through the API, grouped by scope and/or by
-  metric type.
-
-**However, it is not possible to:**
-
-- Limit resources in other OpenStack services once a certain limit has been
-  reached. Ex: block instance creation in Nova above a certain price.
-  Cloudkitty does **rating and only rating**.
-
-- Add taxes, convert between currencies, etc... This needs to be done by a
-  billing software. CloudKitty associates a price to a metric for a given
-  period, but the price's unit is what you decide it to be: euros, dollars,
-  cents, squirrels...
-
-.. _custom scripts: user/rating/pyscripts.html
-
-.. _roadmap: developer/roadmap.html
-
-What changes/features are to expect ?
-=====================================
-
-If you're interested in CloudKitty's evolution, see the project's `roadmap`_ .
-
-.. _hashmap: user/rating/hashmap.html
 
 Documentation contents
 ======================

doc/source/pdf-index.rst

@@ -0,0 +1,40 @@
+======================================
+Welcome to CloudKitty's documentation!
+======================================
+
+.. include:: common-index.rst
+
+Documentation contents
+======================
+
+End User
+--------
+
+.. toctree::
+   :maxdepth: 3
+
+   user/index
+
+Admin / Operator
+----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   admin/index
+
+Developer
+---------
+
+.. toctree::
+   :maxdepth: 2
+
+   developer/index
+
+API Reference
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
+   api-reference/index

doc/source/user/rating/hashmap.rst

@@ -7,10 +7,6 @@ CloudKitty is shipped with core rating modules.
 Hashmap composition
 ===================
 
-You can see hashmap as a simple tree:
-
-.. graphviz:: graph/hashmap.dot
-
 HashMap is composed of different resources and groups.
 
 Group

tox.ini

@@ -57,6 +57,15 @@ commands = oslopolicy-sample-generator --config-file=etc/oslo-policy-generator/c
 basepython = python3
 commands = python setup.py build_sphinx
 
+[testenv:pdf-docs]
+basepython = python3
+envdir = {toxworkdir}/docs
+whitelist_externals =
+  make
+commands =
+  sphinx-build -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:venv]
 basepython = python3
 commands = {posargs}