Generate PDF documentation

For PDFLaTeX, remove the irrelevant parts (contributing,
search) and those that break (full config examples).
Additionally, this replaces fancy quotes as they don't work
in PDFLaTeX either (it handles regular quotes internally).

Change-Id: I60459407e49a88c2231217152fc078346e5f4b4f
Co-Authored-By: Radosław Piliszek <radoslaw.piliszek@gmail.com>

doc/requirements.txt

@@ -8,3 +8,6 @@ sphinxcontrib-apidoc>=0.2.0  # BSD
 
 # releasenotes
 reno>=3.1.0 # Apache-2.0
+
+# PDF Docs
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD

doc/source/cli/index.rst

@@ -2,7 +2,7 @@
 Masakari CLI Documentation
 ==========================
 
-In this section you will find information on Masakari’s command line
+In this section you will find information on Masakari's command line
 interface.
 
 .. toctree::

doc/source/conf.py

@@ -85,15 +85,20 @@ openstackdocs_auto_name = False
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 
+# -- Options for LaTeX output -------------------------------------------------
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
     ('index',
-     '%s.tex' % project,
+     'doc-%s.tex' % project,
      '%s Documentation' % project,
      'OpenStack Foundation', 'manual'),
 ]
 
-# Example configuration for intersphinx: refer to the Python standard library.
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
-#intersphinx_mapping = {'http://docs.python.org/': None}
+latex_use_xindy = False
+
+# Disable smartquotes, they don't work in latex
+smartquotes_excludes = {'builders': ['latex']}

doc/source/configuration/config.rst

@@ -3,7 +3,11 @@ Configuration Options
 =====================
 
 The following is an overview of all available configuration options in
-Masakari. For a sample configuration file, refer to :doc:`sample_config`.
+Masakari.
+
+.. only:: html
+
+   For a sample configuration file, refer to :doc:`sample_config`.
 
 .. show-options::
    :config-file: etc/masakari/masakari-config-generator.conf

doc/source/configuration/index.rst

@@ -13,14 +13,18 @@ Masakari has two main config files:
 * :doc:`Config Reference <config>`: A complete reference of all
   config points in masakari and what they impact.
 
-* :doc:`Sample Config File <sample_config>`: A sample config
+.. only:: html
-  file with inline documentation.
+
+   * :doc:`Sample Config File <sample_config>`: A sample config
+     file with inline documentation.
 
 * :doc:`Recovery Config Reference <recovery_config>`: A complete reference of all
   config points in masakari and what they impact.
 
-* :doc:`Sample recovery workflow File <recovery_workflow_sample_config>`: A
+.. only:: html
-  complete reference of defining the monitoring processes.
+
+   * :doc:`Sample recovery workflow File <recovery_workflow_sample_config>`: A
+     complete reference of defining the monitoring processes.
 
 Policy
 ------

doc/source/configuration/recovery_config.rst

@@ -3,7 +3,11 @@ Configuration Options
 =====================
 
 The following is an overview of all available configuration options in
-Masakari. For a sample configuration file, refer to :doc:`recovery_workflow_sample_config`.
+Masakari.
+
+.. only:: html
+
+   For a sample configuration file, refer to :doc:`recovery_workflow_sample_config`.
 
 .. show-options::
    :config-file: etc/masakari/masakari-customized-recovery-flow-config-generator.conf

doc/source/index.rst

@@ -77,37 +77,45 @@ Reference Material
    configuration/policy.rst
    configuration/recovery_config.rst
    configuration/recovery_workflow_custom_task.rst
-   configuration/recovery_workflow_sample_config.rst
-   configuration/sample_config.rst
    configuration/sample_policy.rst
    user/architecture.rst
    user/notifications.rst
 
-Contributor Guide
+.. only:: html
-=================
 
-.. toctree::
+   .. toctree::
-   :maxdepth: 2
+      :hidden:
 
-   user/how_to_get_involved
+      configuration/recovery_workflow_sample_config.rst
-   user/process
+      configuration/sample_config.rst
-   install/development.environment
-   contributor/code_structure
-   contributor/release_notes
 
-For Contributors
+.. only:: html
-================
 
-* If you are a new contributor to Masakari please refer: :doc:`contributor/contributing`
+   Contributor Guide
+   =================
 
-  .. toctree::
+   .. toctree::
-     :hidden:
+      :maxdepth: 2
 
-     contributor/contributing
+      user/how_to_get_involved
+      user/process
+      install/development.environment
+      contributor/code_structure
+      contributor/release_notes
 
-Search
+   For Contributors
-======
+   ================
 
-* :ref:`search`: Search the contents of this document.
+   * If you are a new contributor to Masakari please refer: :doc:`contributor/contributing`
-* `OpenStack wide search <https://docs.openstack.org>`_: Search the wider
+
-  set of OpenStack documentation, including forums.
+      .. toctree::
+         :hidden:
+
+         contributor/contributing
+
+   Search
+   ======
+
+   * :ref:`search`: Search the contents of this document.
+   * `OpenStack wide search <https://docs.openstack.org>`_: Search the wider
+     set of OpenStack documentation, including forums.

doc/source/install/install_and_configure.rst

@@ -20,8 +20,8 @@ Install and configure
 This section describes how to install and configure Masakari services
 on the compute node.
 
-This section assumes that you already have a :doc:`working OpenStack
+This section assumes that you already have a working OpenStack environment with
-environment <development.environment>` with the following components installed:
+the following components installed:
 Nova, Glance, Cinder, Neutron and Identity.
 
 The installation and configuration vary by distribution.

doc/source/install/install_and_configure_ubuntu.rst

@@ -162,9 +162,9 @@ Install and configure Masakari
 
    #. Generate via tox:
 
-      Go to ‘opt/stack/masakari’ and execute the command below, this will generate
+      Go to ``/opt/stack/masakari`` and execute the command below.
-      ``masakari.conf.sample``, sample configuration file at
+      This will generate ``masakari.conf.sample``, a sample configuration file,
-      ``/opt/stack/masakari/etc/masakari/``
+      at ``/opt/stack/masakari/etc/masakari/``:
 
       .. code-block:: console
 

doc/source/user/how_to_get_involved.rst

@@ -62,7 +62,7 @@ How do I get my feature in?
 The best way of getting your feature in is... well it depends.
 
 First concentrate on solving your problem and/or use case, don't fixate
-on getting the code you have working merged. It’s likely things will need
+on getting the code you have working merged. It's likely things will need
 significant re-work after you discuss how your needs match up with all
 the existing ways Masakari is currently being used. The good news, is this
 process should leave you with a feature that's more flexible and doesn't
@@ -196,7 +196,7 @@ http://docs.openstack.org/infra/manual/developers.html#peer-review
 In the draft process guide, I discuss how doing reviews can help get
 your code merged faster: :ref:`process`.
 
-Let’s look at some of the top reasons why participating with code reviews
+Let's look at some of the top reasons why participating with code reviews
 really helps you:
 
 -  Doing more reviews, and seeing what other reviewers notice, will help

tox.ini

@@ -83,6 +83,14 @@ deps = -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/up
 commands =
   sphinx-build -W -b html doc/source doc/build/html
 
+[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
+
 [testenv:releasenotes]
 deps = {[testenv:docs]deps}
 commands =