From 7b47a2a7a4319503570d534cefa61758088918a3 Mon Sep 17 00:00:00 2001 From: sunjia Date: Thu, 3 Oct 2019 16:45:41 +0800 Subject: [PATCH] Generate PDF documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- doc/requirements.txt | 3 ++ doc/source/cli/index.rst | 2 +- doc/source/conf.py | 11 ++-- doc/source/configuration/config.rst | 6 ++- doc/source/configuration/index.rst | 12 +++-- doc/source/configuration/recovery_config.rst | 6 ++- doc/source/index.rst | 52 +++++++++++-------- doc/source/install/install_and_configure.rst | 4 +- .../install/install_and_configure_ubuntu.rst | 6 +-- doc/source/user/how_to_get_involved.rst | 4 +- tox.ini | 8 +++ 11 files changed, 75 insertions(+), 39 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index a25ae2a7..4e367afe 100644 --- a/doc/requirements.txt +++ b/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 diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index f6e3e302..e264fd46 100644 --- a/doc/source/cli/index.rst +++ b/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:: diff --git a/doc/source/conf.py b/doc/source/conf.py index ac5d3d62..fc5bd4a2 100755 --- a/doc/source/conf.py +++ b/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. -#intersphinx_mapping = {'http://docs.python.org/': None} +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +latex_use_xindy = False + +# Disable smartquotes, they don't work in latex +smartquotes_excludes = {'builders': ['latex']} diff --git a/doc/source/configuration/config.rst b/doc/source/configuration/config.rst index 4824a9f0..2ef7cb67 100644 --- a/doc/source/configuration/config.rst +++ b/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 diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index be6b445e..548a0dec 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -13,14 +13,18 @@ Masakari has two main config files: * :doc:`Config Reference `: A complete reference of all config points in masakari and what they impact. -* :doc:`Sample Config File `: A sample config - file with inline documentation. +.. only:: html + + * :doc:`Sample Config File `: A sample config + file with inline documentation. * :doc:`Recovery Config Reference `: A complete reference of all config points in masakari and what they impact. -* :doc:`Sample recovery workflow File `: A - complete reference of defining the monitoring processes. +.. only:: html + + * :doc:`Sample recovery workflow File `: A + complete reference of defining the monitoring processes. Policy ------ diff --git a/doc/source/configuration/recovery_config.rst b/doc/source/configuration/recovery_config.rst index ed949ca5..a431acef 100644 --- a/doc/source/configuration/recovery_config.rst +++ b/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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 02cc8ccd..5d061b0d 100644 --- a/doc/source/index.rst +++ b/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:: - :maxdepth: 2 + .. toctree:: + :hidden: - user/how_to_get_involved - user/process - install/development.environment - contributor/code_structure - contributor/release_notes + configuration/recovery_workflow_sample_config.rst + configuration/sample_config.rst -For Contributors -================ +.. only:: html -* If you are a new contributor to Masakari please refer: :doc:`contributor/contributing` + Contributor Guide + ================= - .. toctree:: - :hidden: + .. toctree:: + :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. -* `OpenStack wide search `_: Search the wider - set of OpenStack documentation, including forums. + * If you are a new contributor to Masakari please refer: :doc:`contributor/contributing` + + .. toctree:: + :hidden: + + contributor/contributing + + Search + ====== + + * :ref:`search`: Search the contents of this document. + * `OpenStack wide search `_: Search the wider + set of OpenStack documentation, including forums. diff --git a/doc/source/install/install_and_configure.rst b/doc/source/install/install_and_configure.rst index 9ee8cf99..6a0be591 100644 --- a/doc/source/install/install_and_configure.rst +++ b/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 -environment ` with the following components installed: +This section assumes that you already have a working OpenStack environment with +the following components installed: Nova, Glance, Cinder, Neutron and Identity. The installation and configuration vary by distribution. diff --git a/doc/source/install/install_and_configure_ubuntu.rst b/doc/source/install/install_and_configure_ubuntu.rst index 8a932371..f75880be 100644 --- a/doc/source/install/install_and_configure_ubuntu.rst +++ b/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 - ``masakari.conf.sample``, sample configuration file at - ``/opt/stack/masakari/etc/masakari/`` + Go to ``/opt/stack/masakari`` and execute the command below. + This will generate ``masakari.conf.sample``, a sample configuration file, + at ``/opt/stack/masakari/etc/masakari/``: .. code-block:: console diff --git a/doc/source/user/how_to_get_involved.rst b/doc/source/user/how_to_get_involved.rst index 6c995e6c..362670d5 100644 --- a/doc/source/user/how_to_get_involved.rst +++ b/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 diff --git a/tox.ini b/tox.ini index b13c4c4c..f6aea4e5 100644 --- a/tox.ini +++ b/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 =