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 =