openstack/masakari
Code Issues Proposed changes

Generate PDF documentation

Browse Source 
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>
This commit is contained in:
sunjia 2019-10-03 16:45:41 +08:00 committed by Radosław Piliszek
parent f979628edc
commit 7b47a2a7a4
11 changed files with 75 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/requirements.txt
View File

@ -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

2
doc/source/cli/index.rst
View File

@ -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::

11
doc/source/conf.py
View File

@ -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']}

6
doc/source/configuration/config.rst
View File

@ -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

12
doc/source/configuration/index.rst
View File

@ -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
file with inline documentation.
.. only:: html
* :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
complete reference of defining the monitoring processes.
.. only:: html
* :doc:`Sample recovery workflow File <recovery_workflow_sample_config>`: A
complete reference of defining the monitoring processes.
Policy
------

6
doc/source/configuration/recovery_config.rst
View File

@ -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

52
doc/source/index.rst
View File

@ -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 <https://docs.openstack.org>`_: 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 <https://docs.openstack.org>`_: Search the wider
set of OpenStack documentation, including forums.

4
doc/source/install/install_and_configure.rst
View File

@ -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 <development.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.

6
doc/source/install/install_and_configure_ubuntu.rst
View File

@ -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

4
doc/source/user/how_to_get_involved.rst
View File

@ -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

8
tox.ini
View File

@ -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 =