diff --git a/doc/source/conf.py b/doc/source/conf.py index f21a0550c7..b1120da6fa 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -78,10 +78,23 @@ htmlhelp_basename = 'magnumdoc' # [howto/manual]). latex_documents = [ ('index', - 'magnum.tex', + 'doc-magnum.tex', u'magnum Documentation', u'OpenStack Foundation', 'manual'), ] +# If false, no module index is generated. +latex_domain_indices = False + +latex_elements = { + 'makeindex': '', + 'printindex': '', + 'preamble': r'\setcounter{tocdepth}{3}', + 'maxlistdepth': 10, +} + +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +latex_use_xindy = False + # Example configuration for intersphinx: refer to the Python standard library. # intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/configuration/sample-config.rst b/doc/source/configuration/sample-config.rst index f38c7e7e48..86420a782f 100644 --- a/doc/source/configuration/sample-config.rst +++ b/doc/source/configuration/sample-config.rst @@ -7,7 +7,14 @@ auto-generated from Magnum when this documentation is built, so if you are having issues with an option, please compare your version of Magnum with the version of this documentation. -The sample configuration can also be viewed in :download:`file form -`. +.. only:: html -.. literalinclude:: /_static/magnum.conf.sample + The sample configuration can also be viewed in :download:`file form + `. + + .. literalinclude:: /_static/magnum.conf.sample + +.. only:: latex + + See the online version of this documentation for the full example config + file. diff --git a/doc/source/user/glossary.rst b/doc/source/user/glossary.rst index 8a33486daf..9bdf82e24a 100644 --- a/doc/source/user/glossary.rst +++ b/doc/source/user/glossary.rst @@ -9,73 +9,73 @@ Magnum Terminology .. glossary:: -Cluster (previously Bay) - A cluster is the construct in which Magnum launches container orchestration - engines. After a cluster has been created the user is able to add containers - to it either directly, or in the case of the Kubernetes container - orchestration engine within pods - a logical construct specific to that - implementation. A cluster is created based on a ClusterTemplate. + Cluster (previously Bay) + A cluster is the construct in which Magnum launches container orchestration + engines. After a cluster has been created the user is able to add containers + to it either directly, or in the case of the Kubernetes container + orchestration engine within pods - a logical construct specific to that + implementation. A cluster is created based on a ClusterTemplate. -ClusterTemplate (previously BayModel) - A ClusterTemplate in Magnum is roughly equivalent to a flavor in Nova. It - acts as a template that defines options such as the container orchestration - engine, keypair and image for use when Magnum is creating clusters using - the given ClusterTemplate. + ClusterTemplate (previously BayModel) + A ClusterTemplate in Magnum is roughly equivalent to a flavor in Nova. It + acts as a template that defines options such as the container orchestration + engine, keypair and image for use when Magnum is creating clusters using + the given ClusterTemplate. -Container Orchestration Engine (COE) - A container orchestration engine manages the lifecycle of one or more - containers, logically represented in Magnum as a cluster. Magnum supports a - number of container orchestration engines, each with their own pros and cons, - including Docker Swarm, Kubernetes, and Mesos. + Container Orchestration Engine (COE) + A container orchestration engine manages the lifecycle of one or more + containers, logically represented in Magnum as a cluster. Magnum supports a + number of container orchestration engines, each with their own pros and cons, + including Docker Swarm, Kubernetes, and Mesos. -Labels - Labels is a general method to specify supplemental parameters that are - specific to certain COE or associated with certain options. Their - format is key/value pair and their meaning is interpreted by the - drivers that uses them. + Labels + Labels is a general method to specify supplemental parameters that are + specific to certain COE or associated with certain options. Their + format is key/value pair and their meaning is interpreted by the + drivers that uses them. -Cluster Drivers - A cluster driver is a collection of python code, heat templates, scripts, - images, and documents for a particular COE on a particular distro. Magnum - presents the concept of ClusterTemplates and clusters. The implementation - for a particular cluster type is provided by the cluster driver. In other - words, the cluster driver provisions and manages the infrastructure for the - COE. + Cluster Drivers + A cluster driver is a collection of python code, heat templates, scripts, + images, and documents for a particular COE on a particular distro. Magnum + presents the concept of ClusterTemplates and clusters. The implementation + for a particular cluster type is provided by the cluster driver. In other + words, the cluster driver provisions and manages the infrastructure for the + COE. Kubernetes Terminology ~~~~~~~~~~~~~~~~~~~~~~ -.. glossary:: - Kubernetes uses a range of terminology that we refer to in this guide. We define these common terms for your reference: -Pod - When using the Kubernetes container orchestration engine, a pod is the - smallest deployable unit that can be created and managed. A pod is a - co-located group of application containers that run with a shared context. - When using Magnum, pods are created and managed within clusters. Refer to the - `pods section `_ in - `Kubernetes Tasks`_ for more information. +.. glossary:: -Replication controller - A replication controller is used to ensure that at any given time a certain - number of replicas of a pod are running. Pods are automatically created and - deleted by the replication controller as necessary based on a template to - ensure that the defined number of replicas exist. Refer to the `replication - controller section - `_ in - the `Kubernetes Tasks`_ for more information. + Pod + When using the Kubernetes container orchestration engine, a pod is the + smallest deployable unit that can be created and managed. A pod is a + co-located group of application containers that run with a shared context. + When using Magnum, pods are created and managed within clusters. Refer to the + `pods section `_ in + `Kubernetes Tasks`_ for more information. -Service - A service is an additional layer of abstraction provided by the Kubernetes - container orchestration engine which defines a logical set of pods and a - policy for accessing them. This is useful because pods are created and - deleted by a replication controller, for example, other pods needing to - discover them can do so via the service abstraction. Refer to the - `services section - `_ in - `Kubernetes Concepts`_ for more information. + Replication controller + A replication controller is used to ensure that at any given time a certain + number of replicas of a pod are running. Pods are automatically created and + deleted by the replication controller as necessary based on a template to + ensure that the defined number of replicas exist. Refer to the `replication + controller section + `_ in + the `Kubernetes Tasks`_ for more information. + + Service + A service is an additional layer of abstraction provided by the Kubernetes + container orchestration engine which defines a logical set of pods and a + policy for accessing them. This is useful because pods are created and + deleted by a replication controller, for example, other pods needing to + discover them can do so via the service abstraction. Refer to the + `services section + `_ in + `Kubernetes Concepts`_ for more information. .. _Kubernetes Tasks: https://kubernetes.io/docs/tasks/ .. _Kubernetes Concepts: https://kubernetes.io/docs/concepts/ diff --git a/tox.ini b/tox.ini index edbe30371e..5eaee543ec 100644 --- a/tox.ini +++ b/tox.ini @@ -138,6 +138,15 @@ basepython = python3 deps = -r{toxinidir}/doc/requirements.txt commands = sphinx-build -W -b html doc/source doc/build/html +[testenv:pdf-docs] +basepython = python3 +deps = {[testenv:docs]deps} +whitelist_externals = + make +commands = + sphinx-build -b latex doc/source doc/build/pdf + make -C doc/build/pdf + [testenv:genconfig] basepython = python3 commands =