From 5700f022897365492cc0ccf113ab5cba9cf03fc0 Mon Sep 17 00:00:00 2001 From: Simon Pasquier Date: Fri, 18 Sep 2015 17:45:07 +0200 Subject: [PATCH] Add documentation placeholder Change-Id: I1b324fe92805cc8e054a81709001114fda7b53da --- doc/.gitignore | 1 + doc/Makefile | 177 ++++++++++++++++++++++++++++++++++++ doc/source/_static/.gitkeep | 0 doc/source/appendix.rst | 6 ++ doc/source/conf.py | 27 ++++++ doc/source/index.rst | 21 +++++ doc/source/installation.rst | 6 ++ doc/source/licenses.rst | 23 +++++ doc/source/news.rst | 6 ++ doc/source/overview.rst | 22 +++++ doc/source/user.rst | 6 ++ test-requirements.txt | 1 + tox.ini | 11 ++- 13 files changed, 306 insertions(+), 1 deletion(-) create mode 100644 doc/.gitignore create mode 100644 doc/Makefile create mode 100644 doc/source/_static/.gitkeep create mode 100644 doc/source/appendix.rst create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst create mode 100644 doc/source/installation.rst create mode 100644 doc/source/licenses.rst create mode 100644 doc/source/news.rst create mode 100644 doc/source/overview.rst create mode 100644 doc/source/user.rst create mode 100644 test-requirements.txt diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..567609b --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..77c31e9 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(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/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/LMAcollector.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/LMAcollector.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/LMAcollector" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/LMAcollector" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/source/_static/.gitkeep b/doc/source/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/appendix.rst b/doc/source/appendix.rst new file mode 100644 index 0000000..f009e3f --- /dev/null +++ b/doc/source/appendix.rst @@ -0,0 +1,6 @@ +.. _user_appendix: + +Appendix +======== + +TBD diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..0788de2 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,27 @@ +# Always use the default theme for Readthedocs +RTD_NEW_THEME = True + +extensions = [] +templates_path = ['_templates'] + +source_suffix = '.rst' + +master_doc = 'index' + +project = u'The LMA Infrastructure Alerting plugin for Fuel' +copyright = u'2015, Mirantis Inc.' + +version = '0.8' +release = '0.8.0' + +exclude_patterns = [] + +pygments_style = 'sphinx' + +html_theme = 'classic' +html_static_path = ['_static'] + +latex_documents = [ + ('index', 'LMAInfrastructureAlerting.tex', u'The LMA Infrastructure Alerting plugin for Fuel Documentation', + u'Mirantis Inc.', 'manual'), +] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..8ae7ecc --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,21 @@ +================================================================================== +Welcome to the Mirantis OpenStack LMA Infrastructure Alering Plugin Documentation! +================================================================================== + +User documentation +================== + +.. toctree:: + :maxdepth: 2 + + overview + news + installation + user + licenses + appendix + +Indices and Tables +================== + +* :ref:`search` diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 0000000..3733bea --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,6 @@ +.. _user_installation: + +Installation Guide +================== + +TBD diff --git a/doc/source/licenses.rst b/doc/source/licenses.rst new file mode 100644 index 0000000..ba5e65d --- /dev/null +++ b/doc/source/licenses.rst @@ -0,0 +1,23 @@ +.. _licenses: + +Licenses +======== + +Third Party Components +---------------------- + ++------+------------------+---------+ +| Name | Project Web Site | License | ++======+==================+=========+ +| | | | ++------+------------------+---------+ + +Puppet modules +-------------- + ++------+------------------+---------+ +| Name | Project Web Site | License | ++======+==================+=========+ +| | | | ++------+------------------+---------+ + diff --git a/doc/source/news.rst b/doc/source/news.rst new file mode 100644 index 0000000..62441b6 --- /dev/null +++ b/doc/source/news.rst @@ -0,0 +1,6 @@ +.. _news: + +What's new in 0.8 +================= + +TBD diff --git a/doc/source/overview.rst b/doc/source/overview.rst new file mode 100644 index 0000000..275d7a7 --- /dev/null +++ b/doc/source/overview.rst @@ -0,0 +1,22 @@ +.. _user_overview: + +Overview +======== + +TBD + +.. _plugin_requirements: + +Requirements +------------ + ++-------------------------------------------------------+-----------------------------------------------------------------+ +| Requirement | Version/Comment | ++=======================================================+=================================================================+ +| Fuel | 7.0 | ++-------------------------------------------------------+-----------------------------------------------------------------+ + +Limitations +----------- + +TBD diff --git a/doc/source/user.rst b/doc/source/user.rst new file mode 100644 index 0000000..aef83cd --- /dev/null +++ b/doc/source/user.rst @@ -0,0 +1,6 @@ +.. _user_guide: + +User Guide +========== + +TBD diff --git a/test-requirements.txt b/test-requirements.txt new file mode 100644 index 0000000..2806c16 --- /dev/null +++ b/test-requirements.txt @@ -0,0 +1 @@ +Sphinx diff --git a/tox.ini b/tox.ini index 8de6c54..414874b 100644 --- a/tox.ini +++ b/tox.ini @@ -1,7 +1,10 @@ [tox] -envlist = manifests,nagios,lma_infra_alerting +envlist = manifests,nagios,lma_infra_alerting,docs skipsdist = True +[testenv] +deps = -r{toxinidir}/test-requirements.txt + [testenv:manifests] deps = changedir = {toxinidir}/deployment_scripts/puppet/manifests @@ -40,3 +43,9 @@ commands = mkdir -p {toxinidir}/.bundled_gems bundle install bundle exec rake test + +[testenv:docs] +changedir = {toxinidir}/doc +whitelist_externals = make +commands = + make clean html SPHINXOPTS=-W