summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNadya Shakhat <nprivalova@mirantis.com>2016-06-15 14:30:39 +0300
committerNadya Shakhat <nprivalova@mirantis.com>2016-06-15 14:31:58 +0300
commit4fec0439df45a7e6df0ac5367f186c89dc646a5d (patch)
tree7290cc550e815f9b1229bbff6ab348f8780855b6
parent522de005bd2db9989d91e31151c3290dd73cd452 (diff)
Add Sphinx support
Notes
Notes (review): Code-Review+2: Nadya Shakhat <nprivalova@mirantis.com> Workflow+1: Nadya Shakhat <nprivalova@mirantis.com> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Tue, 21 Jun 2016 15:04:45 +0000 Reviewed-on: https://review.openstack.org/329882 Project: openstack/fuel-plugin-ceilometer-redis Branch: refs/heads/master
-rw-r--r--.gitignore2
-rw-r--r--doc/.gitignore2
-rw-r--r--doc/Makefile191
-rw-r--r--doc/content/tests.rst0
-rw-r--r--doc/source/conf.py32
-rw-r--r--doc/source/description.rst (renamed from doc/content/description.rst)3
-rw-r--r--doc/source/guide.rst (renamed from doc/content/guide.rst)11
-rw-r--r--doc/source/images/redis-plugin-8.0.png (renamed from doc/content/images/redis-plugin-8.0.png)bin84459 -> 84459 bytes
-rw-r--r--doc/source/images/redis-plugin-on.png (renamed from doc/content/images/redis-plugin-on.png)bin104845 -> 104845 bytes
-rw-r--r--doc/source/images/redis-plugin-on8.0.png (renamed from doc/content/images/redis-plugin-on8.0.png)bin70348 -> 70348 bytes
-rw-r--r--doc/source/images/redis-plugin.png (renamed from doc/content/images/redis-plugin.png)bin65217 -> 65217 bytes
-rw-r--r--doc/source/index.rst15
-rw-r--r--doc/source/installation.rst (renamed from doc/content/installation.rst)3
-rw-r--r--test-requirements.txt4
-rw-r--r--tox.ini18
15 files changed, 271 insertions, 10 deletions
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..fba73ee
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
1.build/
2.tox
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..8d60ee6
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,2 @@
1build/
2images/*.pdf
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..5cad1b5
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,191 @@
1# Makefile for Sphinx documentation
2#
3
4# You can set these variables from the command line.
5SPHINXOPTS =
6SPHINXBUILD = sphinx-build
7PAPER =
8BUILDDIR = build
9
10# User-friendly check for sphinx-build
11ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13endif
14
15# Internal variables.
16PAPEROPT_a4 = -D latex_paper_size=a4
17PAPEROPT_letter = -D latex_paper_size=letter
18ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
19# the i18n builder cannot share the environment and doctrees with the others
20I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
21# SVG to PDF conversion
22SVG2PDF = inkscape
23SVG2PDF_FLAGS =
24# Build a list of SVG files to convert to PDF
25PDF_FILES := $(foreach dir, images, $(patsubst %.svg,%.pdf,$(wildcard $(dir)/*.svg)))
26
27
28.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
29
30help:
31 @echo "Please use \`make <target>' where <target> is one of"
32 @echo " html to make standalone HTML files"
33 @echo " dirhtml to make HTML files named index.html in directories"
34 @echo " singlehtml to make a single large HTML file"
35 @echo " pickle to make pickle files"
36 @echo " json to make JSON files"
37 @echo " htmlhelp to make HTML files and a HTML help project"
38 @echo " qthelp to make HTML files and a qthelp project"
39 @echo " devhelp to make HTML files and a Devhelp project"
40 @echo " epub to make an epub"
41 @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
42 @echo " latexpdf to make LaTeX files and run them through pdflatex"
43 @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
44 @echo " text to make text files"
45 @echo " man to make manual pages"
46 @echo " texinfo to make Texinfo files"
47 @echo " info to make Texinfo files and run them through makeinfo"
48 @echo " gettext to make PO message catalogs"
49 @echo " changes to make an overview of all changed/added/deprecated items"
50 @echo " xml to make Docutils-native XML files"
51 @echo " pseudoxml to make pseudoxml-XML files for display purposes"
52 @echo " linkcheck to check all external links for integrity"
53 @echo " doctest to run all doctests embedded in the documentation (if enabled)"
54
55clean:
56 rm -rf $(BUILDDIR)/*
57 rm -f $(PDF_FILES)
58
59html:
60 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
61 @echo
62 @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
63
64dirhtml:
65 $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
66 @echo
67 @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
68
69singlehtml:
70 $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
71 @echo
72 @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
73
74pickle:
75 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
76 @echo
77 @echo "Build finished; now you can process the pickle files."
78
79json:
80 $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
81 @echo
82 @echo "Build finished; now you can process the JSON files."
83
84htmlhelp:
85 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
86 @echo
87 @echo "Build finished; now you can run HTML Help Workshop with the" \
88 ".hhp project file in $(BUILDDIR)/htmlhelp."
89
90qthelp:
91 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
92 @echo
93 @echo "Build finished; now you can run "qcollectiongenerator" with the" \
94 ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
95 @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/LMAcollector.qhcp"
96 @echo "To view the help file:"
97 @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/LMAcollector.qhc"
98
99devhelp:
100 $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
101 @echo
102 @echo "Build finished."
103 @echo "To view the help file:"
104 @echo "# mkdir -p $$HOME/.local/share/devhelp/LMAcollector"
105 @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/LMAcollector"
106 @echo "# devhelp"
107
108epub:
109 $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
110 @echo
111 @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
112
113latex: $(PDF_FILES)
114 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
115 @echo
116 @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
117 @echo "Run \`make' in that directory to run these through (pdf)latex" \
118 "(use \`make latexpdf' here to do that automatically)."
119
120latexpdf: $(PDF_FILES)
121 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
122 @echo "Running LaTeX files through pdflatex..."
123 $(MAKE) -C $(BUILDDIR)/latex all-pdf
124 @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
125
126latexpdfja:
127 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
128 @echo "Running LaTeX files through platex and dvipdfmx..."
129 $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
130 @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
131
132text:
133 $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
134 @echo
135 @echo "Build finished. The text files are in $(BUILDDIR)/text."
136
137man:
138 $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
139 @echo
140 @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
141
142texinfo:
143 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144 @echo
145 @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
146 @echo "Run \`make' in that directory to run these through makeinfo" \
147 "(use \`make info' here to do that automatically)."
148
149info:
150 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
151 @echo "Running Texinfo files through makeinfo..."
152 make -C $(BUILDDIR)/texinfo info
153 @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
154
155gettext:
156 $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
157 @echo
158 @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
159
160changes:
161 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
162 @echo
163 @echo "The overview file is in $(BUILDDIR)/changes."
164
165linkcheck:
166 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
167 @echo
168 @echo "Link check complete; look for any errors in the above output " \
169 "or in $(BUILDDIR)/linkcheck/output.txt."
170
171doctest:
172 $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
173 @echo "Testing of doctests in the sources finished, look at the " \
174 "results in $(BUILDDIR)/doctest/output.txt."
175
176xml:
177 $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
178 @echo
179 @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
180
181pseudoxml:
182 $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
183 @echo
184 @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
185
186# Rule for building the PDF files only
187images: $(PDF_FILES)
188
189# Pattern rule for converting SVG to PDF
190%.pdf : %.svg
191 $(SVG2PDF) -f $< -A $@
diff --git a/doc/content/tests.rst b/doc/content/tests.rst
deleted file mode 100644
index e69de29..0000000
--- a/doc/content/tests.rst
+++ /dev/null
diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 0000000..9909511
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,32 @@
1import sys
2import os
3extensions = []
4templates_path = ['_templates']
5source_suffix = '.rst'
6master_doc = 'index'
7project = u'The Redis Plugin for Ceilometer documentation'
8copyright = u'2016, Mirantis Inc.'
9version = '0.1'
10release = '0.1.0'
11exclude_patterns = [
12]
13pygments_style = 'sphinx'
14html_theme = 'default'
15htmlhelp_basename = 'RedisPlugindoc'
16latex_elements = {
17}
18latex_documents = [
19 ('index', 'RedisPlugindoc.tex', u'The Redis Plugin for Ceilometer documentation',
20 u'Mirantis Inc.', 'manual'),
21]
22man_pages = [
23 ('index', 'redisplugin', u'The Redis Plugin for Ceilometer documentation',
24 [u'Mirantis Inc.'], 1)
25]
26texinfo_documents = [
27 ('index', 'RedisPlugin', u'The Redis Plugin for Ceilometer documentation',
28 u'Mirantis Inc.', 'RedisPlugin', 'One line description of project.',
29 'Miscellaneous'),
30]
31latex_elements = {'classoptions': ',openany,oneside', 'babel':
32 '\\usepackage[english]{babel}'}
diff --git a/doc/content/description.rst b/doc/source/description.rst
index e30636c..1ea9019 100644
--- a/doc/content/description.rst
+++ b/doc/source/description.rst
@@ -73,7 +73,4 @@ Limitations
73 ceilometer's pipeline.yaml. Thus, you need to configure it manually if you want to use transformers. 73 ceilometer's pipeline.yaml. Thus, you need to configure it manually if you want to use transformers.
74 If you don't need this feature, it is recommended to disable coordination for the notification agents. 74 If you don't need this feature, it is recommended to disable coordination for the notification agents.
75 75
76.. include:: installation.rst
77.. include:: guide.rst
78
79 76
diff --git a/doc/content/guide.rst b/doc/source/guide.rst
index f394c16..bbf089e 100644
--- a/doc/content/guide.rst
+++ b/doc/source/guide.rst
@@ -1,7 +1,7 @@
1User Guide 1User Guide
2========== 2==========
3 3
4Once the Ceilometer Redis plugin plugin has been installed (following `Installation Guide`_), you can 4Once the Ceilometer Redis plugin plugin has been installed (following :ref:`Installation Guide`), you can
5create *OpenStack* environments with Ceilometer whose Central agents, Notification agent and Alarm evaluator 5create *OpenStack* environments with Ceilometer whose Central agents, Notification agent and Alarm evaluator
6work in workload_partitioned mode. 6work in workload_partitioned mode.
7 7
@@ -29,8 +29,7 @@ Plugin configuration in MOS 8.0
29 .. image:: images/redis-plugin-8.0.png 29 .. image:: images/redis-plugin-8.0.png
30 :width: 100% 30 :width: 100%
31 31
32#. When 32#. When adding nodes to environment and assigning roles to them <https://docs.mirantis.com/openstack/fuel/fuel-8.0/operations.html#adding-redeploying-and-replacing-nodes>`_, please consider using odd number of controllers as mentioned in :ref:`Limitations`.
33 `adding nodes to environment and assigning roles to them <https://docs.mirantis.com/openstack/fuel/fuel-8.0/operations.html#adding-redeploying-and-replacing-nodes>`_, please consider using odd number of controllers as mentioned in `Limitations`_.
34 33
35#. Finish 34#. Finish
36 `environment configuration <https://docs.mirantis.com/openstack/fuel/fuel-8.0/mos-planning-guide.html#fuel-reference-architecture-overview>`_ 35 `environment configuration <https://docs.mirantis.com/openstack/fuel/fuel-8.0/mos-planning-guide.html#fuel-reference-architecture-overview>`_
@@ -55,12 +54,12 @@ Plugin configuration in MOS 7.0
55 :width: 100% 54 :width: 100%
56 55
57#. When 56#. When
58 `adding nodes to environment and assigning roles to them <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#add-nodes-ug>`_, please consider using odd number of controllers as mentioned in `Limitations`_. 57 `adding nodes to environment and assigning roles to them in MOS 7.0 <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#add-nodes-ug>`_, please consider using odd number of controllers as mentioned in :ref:`Limitations`.
59 58
60#. Finish 59#. Finish
61 `environment configuration <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#configure-your-environment>`_ 60 `environment configuration for MOS 7.0 <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#configure-your-environment>`_
62 61
63#. Run `network verification check <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#verify-networks>`_. 62#. Run `network verification check for MOS 7.0 <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#verify-networks>`_.
64 63
65#. Press `Deploy button <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#deploy-changes>`_ to once you are done with environment configuration. 64#. Press `Deploy button <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#deploy-changes>`_ to once you are done with environment configuration.
66 65
diff --git a/doc/content/images/redis-plugin-8.0.png b/doc/source/images/redis-plugin-8.0.png
index 680fca9..680fca9 100644
--- a/doc/content/images/redis-plugin-8.0.png
+++ b/doc/source/images/redis-plugin-8.0.png
Binary files differ
diff --git a/doc/content/images/redis-plugin-on.png b/doc/source/images/redis-plugin-on.png
index b7c5fb6..b7c5fb6 100644
--- a/doc/content/images/redis-plugin-on.png
+++ b/doc/source/images/redis-plugin-on.png
Binary files differ
diff --git a/doc/content/images/redis-plugin-on8.0.png b/doc/source/images/redis-plugin-on8.0.png
index d25cc00..d25cc00 100644
--- a/doc/content/images/redis-plugin-on8.0.png
+++ b/doc/source/images/redis-plugin-on8.0.png
Binary files differ
diff --git a/doc/content/images/redis-plugin.png b/doc/source/images/redis-plugin.png
index bad25b8..bad25b8 100644
--- a/doc/content/images/redis-plugin.png
+++ b/doc/source/images/redis-plugin.png
Binary files differ
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 0000000..fe347f9
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,15 @@
1========================================================================
2Welcome to the Ceilometer Redis Plugin Documentation!
3========================================================================
4
5.. toctree::
6 :maxdepth: 2
7
8 description
9 guide
10 installation
11
12Indices and Tables
13==================
14
15* :ref:`search`
diff --git a/doc/content/installation.rst b/doc/source/installation.rst
index fcbe272..53f3d6e 100644
--- a/doc/content/installation.rst
+++ b/doc/source/installation.rst
@@ -1,3 +1,4 @@
1.. _installation guide:
1 2
2Installation Guide 3Installation Guide
3================== 4==================
@@ -7,7 +8,7 @@ Install the Plugin
7 8
8To install the Redis plugin: 9To install the Redis plugin:
9 10
10#. Please refer to `Limitations`_ before you proceed. 11#. Please refer to limitations before you proceed.
11 12
12#. Download the Redis plugin from the 13#. Download the Redis plugin from the
13 `Fuel Plugins Catalog <https://www.mirantis.com/products/openstack-drivers-and-plugins/fuel-plugins/>`_. 14 `Fuel Plugins Catalog <https://www.mirantis.com/products/openstack-drivers-and-plugins/fuel-plugins/>`_.
diff --git a/test-requirements.txt b/test-requirements.txt
new file mode 100644
index 0000000..70e5d0a
--- /dev/null
+++ b/test-requirements.txt
@@ -0,0 +1,4 @@
1-e git+https://github.com/openstack/fuel-plugins.git#egg=fuel-plugin-builder
2Sphinx
3# Hacking already pins down pep8, pyflakes and flake8
4hacking<0.11,>=0.10.0
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 0000000..de76db2
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,18 @@
1[tox]
2envlist = docs
3skipsdist = True
4
5[testenv]
6deps = -r{toxinidir}/test-requirements.txt
7passenv = HOME
8
9[flake8]
10ignore = H105,H201,E241,H401
11show-source = True
12
13[testenv:docs]
14changedir = {toxinidir}/doc
15whitelist_externals = make
16commands =
17 make clean html SPHINXOPTS=-W
18