openstack/magnum
Code Issues Proposed changes

PDF documentation build

Browse Source 
Change-Id: Idc50caec499d899e18231bae9e40a0c6af2ca506
This commit is contained in:
matthew-fuller
2019-09-24 15:59:12 -07:00
committed by Matthew Fuller
parent a0c894a222
commit a65e055024
4 changed files with 87 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
doc/source/conf.py
View File

@@ -78,10 +78,23 @@ htmlhelp_basename = 'magnumdoc'
# [howto/manual]). # [howto/manual]).
latex_documents = [ latex_documents = [
('index', ('index',
'magnum.tex', 'doc-magnum.tex',
u'magnum Documentation', u'magnum Documentation',
u'OpenStack Foundation', 'manual'), 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. # Example configuration for intersphinx: refer to the Python standard library.
# intersphinx_mapping = {'http://docs.python.org/': None} # intersphinx_mapping = {'http://docs.python.org/': None}

13
doc/source/configuration/sample-config.rst
View File

@@ -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 if you are having issues with an option, please compare your version of
Magnum with the version of this documentation. Magnum with the version of this documentation.
The sample configuration can also be viewed in :download:`file form .. only:: html
</_static/magnum.conf.sample>`.
.. literalinclude:: /_static/magnum.conf.sample The sample configuration can also be viewed in :download:`file form
</_static/magnum.conf.sample>`.
.. literalinclude:: /_static/magnum.conf.sample
.. only:: latex
See the online version of this documentation for the full example config
file.

108
doc/source/user/glossary.rst
View File

@@ -9,73 +9,73 @@ Magnum Terminology
.. glossary:: .. glossary::
Cluster (previously Bay) Cluster (previously Bay)
A cluster is the construct in which Magnum launches container orchestration 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 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 to it either directly, or in the case of the Kubernetes container
orchestration engine within pods - a logical construct specific to that orchestration engine within pods - a logical construct specific to that
implementation. A cluster is created based on a ClusterTemplate. implementation. A cluster is created based on a ClusterTemplate.
ClusterTemplate (previously BayModel) ClusterTemplate (previously BayModel)
A ClusterTemplate in Magnum is roughly equivalent to a flavor in Nova. It 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 acts as a template that defines options such as the container orchestration
engine, keypair and image for use when Magnum is creating clusters using engine, keypair and image for use when Magnum is creating clusters using
the given ClusterTemplate. the given ClusterTemplate.
Container Orchestration Engine (COE) Container Orchestration Engine (COE)
A container orchestration engine manages the lifecycle of one or more A container orchestration engine manages the lifecycle of one or more
containers, logically represented in Magnum as a cluster. Magnum supports a containers, logically represented in Magnum as a cluster. Magnum supports a
number of container orchestration engines, each with their own pros and cons, number of container orchestration engines, each with their own pros and cons,
including Docker Swarm, Kubernetes, and Mesos. including Docker Swarm, Kubernetes, and Mesos.
Labels Labels
Labels is a general method to specify supplemental parameters that are Labels is a general method to specify supplemental parameters that are
specific to certain COE or associated with certain options. Their specific to certain COE or associated with certain options. Their
format is key/value pair and their meaning is interpreted by the format is key/value pair and their meaning is interpreted by the
drivers that uses them. drivers that uses them.
Cluster Drivers Cluster Drivers
A cluster driver is a collection of python code, heat templates, scripts, A cluster driver is a collection of python code, heat templates, scripts,
images, and documents for a particular COE on a particular distro. Magnum images, and documents for a particular COE on a particular distro. Magnum
presents the concept of ClusterTemplates and clusters. The implementation presents the concept of ClusterTemplates and clusters. The implementation
for a particular cluster type is provided by the cluster driver. In other for a particular cluster type is provided by the cluster driver. In other
words, the cluster driver provisions and manages the infrastructure for the words, the cluster driver provisions and manages the infrastructure for the
COE. COE.
Kubernetes Terminology Kubernetes Terminology
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
.. glossary::
Kubernetes uses a range of terminology that we refer to in this guide. We Kubernetes uses a range of terminology that we refer to in this guide. We
define these common terms for your reference: define these common terms for your reference:
Pod .. glossary::
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 <https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/>`_ in
`Kubernetes Tasks`_ for more information.
Replication controller Pod
A replication controller is used to ensure that at any given time a certain When using the Kubernetes container orchestration engine, a pod is the
number of replicas of a pod are running. Pods are automatically created and smallest deployable unit that can be created and managed. A pod is a
deleted by the replication controller as necessary based on a template to co-located group of application containers that run with a shared context.
ensure that the defined number of replicas exist. Refer to the `replication When using Magnum, pods are created and managed within clusters. Refer to the
controller section `pods section <https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/>`_ in
<https://kubernetes.io/docs/tasks/run-application/rolling-update-replication-controller/>`_ in `Kubernetes Tasks`_ for more information.
the `Kubernetes Tasks`_ for more information.
Service Replication controller
A service is an additional layer of abstraction provided by the Kubernetes A replication controller is used to ensure that at any given time a certain
container orchestration engine which defines a logical set of pods and a number of replicas of a pod are running. Pods are automatically created and
policy for accessing them. This is useful because pods are created and deleted by the replication controller as necessary based on a template to
deleted by a replication controller, for example, other pods needing to ensure that the defined number of replicas exist. Refer to the `replication
discover them can do so via the service abstraction. Refer to the controller section
`services section <https://kubernetes.io/docs/tasks/run-application/rolling-update-replication-controller/>`_ in
<https://kubernetes.io/docs/concepts/services-networking/service/>`_ in the `Kubernetes Tasks`_ for more information.
`Kubernetes Concepts`_ 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
<https://kubernetes.io/docs/concepts/services-networking/service/>`_ in
`Kubernetes Concepts`_ for more information.
.. _Kubernetes Tasks: https://kubernetes.io/docs/tasks/ .. _Kubernetes Tasks: https://kubernetes.io/docs/tasks/
.. _Kubernetes Concepts: https://kubernetes.io/docs/concepts/ .. _Kubernetes Concepts: https://kubernetes.io/docs/concepts/

9
tox.ini
View File

@@ -138,6 +138,15 @@ basepython = python3
deps = -r{toxinidir}/doc/requirements.txt deps = -r{toxinidir}/doc/requirements.txt
commands = sphinx-build -W -b html doc/source doc/build/html 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] [testenv:genconfig]
basepython = python3 basepython = python3
commands = commands =