Improve documentation

.gitignore

@@ -6,6 +6,7 @@
 bin/
 build/
 dist/
+docs/_build/
 include/
 lib/
 man/

README.rst

@@ -1,29 +1,29 @@
-Introduction
-============
+About
+=====
 
 ``fabtools`` includes useful functions to help you write your `Fabric <http://fabfile.org/>`_ files.
 
 ``fabtools`` makes it easier to manage system users, packages, databases, etc.
 
-``fabtools`` includes a number of low-level actions, as well as a higher level interface called ``require``.
+``fabtools`` includes a number of low-level actions, as well as a higher level interface called ``fabtools.require``.
 
-Using ``require`` allows you to use a more declarative style, similar to Chef or Puppet.
+Using ``fabtools.require`` allows you to use a more declarative style, similar to Chef or Puppet.
 
 Installing
 ==========
 
-To install the latest release from PyPI::
+To install the latest release from `PyPI <http://pypi.python.org/pypi/fabtools>`_::
 
     $ pip install fabtools
 
-To install the latest development version from GitHub::
+To install the latest development version from `GitHub <https://github.com/ronnix/fabtools>`_::
 
     $ pip install git+git://github.com/ronnix/fabtools.git
 
 Example
 =======
 
-Here is an example fabfile using ``fabtools``::
+Here is an example ``fabfile.py`` using ``fabtools``::
 
     from fabric.api import *
     from fabtools import require
@@ -76,45 +76,3 @@ Supported targets
 * Ubuntu 11.04
 * Ubuntu 11.10
 * Ubuntu 12.04 LTS
-
-Tests
-=====
-
-Running tests
--------------
-
-If you're using Python 2.7, you can launch the tests using the built-in `unittest <http://docs.python.org/library/unittest.html>`_ runner::
-
-    $ python -m unittest discover
-
-If you're using Python 2.5 or 2.6, you'll need to install `unittest2 <http://pypi.python.org/pypi/unittest2>`_, and use the provided runner::
-
-    $ pip install unittest2
-    $ unit2 discover
-
-Or you can run the tests on all supported Python versions using `tox <http://pypi.python.org/pypi/tox>`_, which will take care of everything::
-
-    $ pip install tox
-    $ tox
-
-Unit tests
-----------
-
-Running unit tests requires the `mock <http://pypi.python.org/pypi/mock/>`_ library.
-
-Functional tests
-----------------
-
-Running functional tests requires `Vagrant <http://vagrantup.com/>`_ to launch virtual machines,
-against which all the tests will be run.
-
-If Vagrant is not installed, the functional tests will be skipped automatically.
-
-If Vagrant is installed, the default is to run the tests on all available base boxes.
-You can specify which base boxes should be used by setting the VAGRANT_BOXES environment variable::
-
-    $ VAGRANT_BOXES='ubuntu_10_04 ubuntu_12_04' tox -e py27
-
-You can also use this to manually disable functional tests::
-
-    $ VAGRANT_BOXES='' tox

docs/Makefile

@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.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 <target>' where <target> 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 "  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 "  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/fabtools.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/fabtools.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/fabtools"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/fabtools"
+	@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."
+
+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."

docs/api/cron.rst

@@ -0,0 +1,7 @@
+.. _cron_module:
+
+:mod:`fabtools.cron`
+--------------------
+
+.. automodule:: fabtools.cron
+    :members:

docs/api/deb.rst

@@ -0,0 +1,9 @@
+.. _deb_module:
+
+:mod:`fabtools.deb`
+-------------------
+
+.. automodule:: fabtools.deb
+    :members:
+
+    .. seealso:: :ref:`require_deb_module`

docs/api/files.rst

@@ -0,0 +1,9 @@
+.. _files_module:
+
+:mod:`fabtools.files`
+---------------------
+
+.. automodule:: fabtools.files
+    :members:
+
+    .. seealso:: :ref:`require_files_module`

docs/api/index.rst

@@ -0,0 +1,21 @@
+fabtools
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   cron
+   deb
+   files
+   mysql
+   network
+   openvz
+   postgres
+   python
+   python_distribute
+   service
+   shorewall
+   supervisor
+   system
+   user
+   vagrant

docs/api/mysql.rst

@@ -0,0 +1,20 @@
+.. _mysql_module:
+
+:mod:`fabtools.mysql`
+---------------------
+
+.. automodule:: fabtools.mysql
+
+    .. seealso:: :ref:`require_mysql_module`
+
+    Manage users
+    ~~~~~~~~~~~~
+
+    .. autofunction:: user_exists
+    .. autofunction:: create_user
+
+    Manage databases
+    ~~~~~~~~~~~~~~~~
+
+    .. autofunction:: database_exists
+    .. autofunction:: create_database

docs/api/network.rst

@@ -0,0 +1,7 @@
+.. _network_module:
+
+:mod:`fabtools.network`
+-----------------------
+
+.. automodule:: fabtools.network
+    :members:

docs/api/openvz.rst

@@ -0,0 +1,38 @@
+.. _openvz_module:
+
+:mod:`fabtools.openvz`
+----------------------
+
+.. automodule:: fabtools.openvz
+
+    .. seealso:: :ref:`require_openvz_module`
+
+    Manage templates
+    ~~~~~~~~~~~~~~~~
+
+    .. autofunction:: download_template
+
+    Manage containers
+    ~~~~~~~~~~~~~~~~~
+
+    .. autofunction:: exists
+    .. autofunction:: create
+    .. autofunction:: set
+    .. autofunction:: status
+    .. autofunction:: start
+    .. autofunction:: stop
+    .. autofunction:: restart
+    .. autofunction:: destroy
+
+
+    Run commands inside a container
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    .. autofunction:: exec2
+    .. autofunction:: guest
+
+    Container class
+    ~~~~~~~~~~~~~~~
+
+    .. autoclass:: fabtools.openvz.container.Container
+        :members:

docs/api/postgres.rst

@@ -0,0 +1,20 @@
+.. _postgres_module:
+
+:mod:`fabtools.postgres`
+------------------------
+
+.. automodule:: fabtools.postgres
+
+    .. seealso:: :ref:`require_postgres_module`
+
+    Manage users
+    ~~~~~~~~~~~~
+
+    .. autofunction:: user_exists
+    .. autofunction:: create_user
+
+    Manage databases
+    ~~~~~~~~~~~~~~~~
+
+    .. autofunction:: database_exists
+    .. autofunction:: create_database