From b7e8323f63b0893b880ce1564ee09fde6db1f40a Mon Sep 17 00:00:00 2001 From: Luka Peschke Date: Wed, 11 Sep 2019 11:49:23 +0200 Subject: [PATCH] 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 | 15 +++++--- doc/source/common-index.rst | 59 +++++++++++++++++++++++++++++ doc/source/conf.py | 14 ++++++- doc/source/index.rst | 60 ++---------------------------- doc/source/pdf-index.rst | 40 ++++++++++++++++++++ doc/source/user/rating/hashmap.rst | 4 -- tox.ini | 9 +++++ 7 files changed, 134 insertions(+), 67 deletions(-) create mode 100644 doc/source/common-index.rst create mode 100644 doc/source/pdf-index.rst diff --git a/doc/source/api-reference/index.rst b/doc/source/api-reference/index.rst index ec45ccf2..ee120c80 100644 --- a/doc/source/api-reference/index.rst +++ b/doc/source/api-reference/index.rst @@ -13,11 +13,14 @@ API v1 v1/* v1/rating/* -API v2 -====== +.. only:: html -.. toctree:: - :maxdepth: 2 - :glob: + API v2 + ====== - v2/* + + .. toctree:: + :maxdepth: 2 + :glob: + + v2/* diff --git a/doc/source/common-index.rst b/doc/source/common-index.rst new file mode 100644 index 00000000..f87a712e --- /dev/null +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py index e113c9e8..71694cf5 100644 --- a/doc/source/conf.py +++ b/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 diff --git a/doc/source/index.rst b/doc/source/index.rst index c021ef8b..a486606f 100644 --- a/doc/source/index.rst +++ b/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. -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 +.. include:: common-index.rst Documentation contents ====================== diff --git a/doc/source/pdf-index.rst b/doc/source/pdf-index.rst new file mode 100644 index 00000000..6c0fa926 --- /dev/null +++ b/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 diff --git a/doc/source/user/rating/hashmap.rst b/doc/source/user/rating/hashmap.rst index b93a9769..1a44ff35 100644 --- a/doc/source/user/rating/hashmap.rst +++ b/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 diff --git a/tox.ini b/tox.ini index 71b5f0b2..34ebbcf7 100644 --- a/tox.ini +++ b/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}