Permalink
Browse files

added Sphinx docs

  • Loading branch information...
1 parent 7ae861e commit 439bab21788907b3f5d1c1b9f866fe6dbe5b4b24 @dexterbt1 committed May 27, 2012
View
@@ -3,6 +3,7 @@ py/lib
py/include
py/build
build/
+docs/_build
dist/
src/*.egg-info
*.egg
View
@@ -1,66 +0,0 @@
-# cuisine\_sweet
-
-Sugar-coated declarative deployment recipes built on top of [Fabric](http://fabfile.org) and [Cuisine](https://github.com/sebastien/cuisine)
-
-
-# Sample fabfile.py
-
- from fabric.api import task, env
- from cuisine_sweet import ensure
-
- env.hosts = [ 'myproject@example.com' ]
-
- @task
- def initial():
- ensure.yum.package_installed('gcc')
- ensure.yum.package_installed('make')
- ensure.yum.package_installed('git')
- ensure.yum.package_installed('python')
- ensure.yum.package_installed('python-devel')
- ensure.supervisord.installed()
-
- @task
- def deploy():
- ensure.local_git.up_to_date(against='origin/master')
- ensure.local_git.clean()
- ensure.git.rsync('git@ourgit.example.com:myproject.git', 'myproject', refspec='master', base_dir='git')
- ensure.user_crontab.loaded('git/myproject/user.cron')
- ensure.supervisord.running('git/myproject/supervisord.conf', '/tmp/myproject.supervisord.pid')
- ensure.supervisord.updated_with_latest_config('git/myproject/supervisord.conf')
-
-
-# Installation
-
-This module is available on PyPI and via Github directly.
-
-* Using pip: `pip install cuisine_sweet`
-* Using setuptools: `easy_install cuisine_sweet`
-* Or clone this repository and do a `python setup install`
-
-
-# Ensure Modules
-
-At the heart of `cuisine_sweet` is the collection of ensure modules. These modules encapsulate
-what is being checked/deployed (declarative), without specifying the how and the where parts
-(imperative). An ensure API is an assertion in the form: ensure.object.state(params)
-
-* git - rsync-style git deployment
-* local\_git - assertions on the current git repo of the fabfile
-* yum - yum package management
-* supervisord - service management via supervisord
-* user\_crontab - user's crontab file/state assertions
-* fs - filesystem related checks/assertions
-* cpan\_module - locallib-flavored perl CPAN module deployments
-
-
-# Warning
-
-This is experimental alpha-quality stuff. The API and implementation are still highly fluid and continuously evolving.
-See LICENSE file for more information.
-
-
-# References
-
-* Fabric - http://fabfile.org
-* Cuisine - https://github.com/sebastien/cuisine
-
View
@@ -0,0 +1,20 @@
+*************
+cuisine_sweet
+*************
+
+Sugar-coated declarative deployment recipes built on top of `Fabric <http://fabfile.org>`_
+and `Cuisine <https://github.com/sebastien/cuisine>`_.
+
+With Fabric's low-level remote ssh orchestration and Cuisine's generic recipes; the goal
+is to build a collection of wrappers capturing various, usually opinionated, system deployment
+styles.
+
+At the heart of ``cuisine_sweet`` is the collection of ``ensure`` modules. These modules encapsulate
+what is being checked/deployed (declarative), without specifying the how and the where parts
+(imperative). An ensure is both an assertion check + action-if-needed in the form:
+``ensure.object.state(params)``.
+
+- `Source Code <http://github.com/dexterbt1/cuisine_sweet>`_
+- `Documentation <http://cuisine_sweet.readthedocs.org/>`_
+- Feedback / Patches - `Create an issue <http://github.com/dexterbt1/cuisine_sweet/issues>`_
+
View
@@ -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/cuisine_sweet.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cuisine_sweet.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/cuisine_sweet"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/cuisine_sweet"
+ @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."
@@ -0,0 +1,55 @@
+Ensure Modules
+==============
+
+:mod:`cpan_module`
+------------------
+
+.. automodule:: cuisine_sweet.ensure.cpan_module
+ :members:
+
+
+:mod:`fs`
+---------
+
+.. automodule:: cuisine_sweet.ensure.fs
+ :members:
+ :show-inheritance:
+
+:mod:`git`
+----------
+
+.. automodule:: cuisine_sweet.ensure.git
+ :members:
+ :show-inheritance:
+
+:mod:`local_git`
+----------------
+
+.. automodule:: cuisine_sweet.ensure.local_git
+ :members:
+ :show-inheritance:
+
+:mod:`supervisord`
+------------------
+
+.. automodule:: cuisine_sweet.ensure.supervisord
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+:mod:`user_crontab`
+-------------------
+
+.. automodule:: cuisine_sweet.ensure.user_crontab
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+:mod:`yum`
+----------
+
+.. automodule:: cuisine_sweet.ensure.yum
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
View
@@ -0,0 +1,32 @@
+Basic Usage
+-----------
+
+``cuisine_sweet`` is to be used in tandem with ``fabric``.
+
+To illustrate usage, see the sample ``fabfile.py`` below::
+
+ from fabric.api import task, env
+ from cuisine_sweet import ensure
+
+ env.hosts = [ 'myproject@server1.example.com', 'myproject@server2.example.com' ]
+
+ @task
+ def initial():
+ ensure.yum.package_installed('gcc')
+ ensure.yum.package_installed('make')
+ ensure.yum.package_installed('git')
+ ensure.yum.package_installed('python')
+ ensure.yum.package_installed('python-devel')
+ ensure.supervisord.installed()
+
+ @task
+ def deploy():
+ ensure.local_git.up_to_date(against='origin/master')
+ ensure.local_git.clean()
+ ensure.git.rsync('git@ourgit.example.com:myproject.git', 'myproject', refspec='master', base_dir='git')
+ ensure.user_crontab.loaded('git/myproject/user.cron')
+ ensure.supervisord.running('git/myproject/supervisord.conf', '/tmp/myproject.supervisord.pid')
+ ensure.supervisord.updated_with_latest_config('git/myproject/supervisord.conf')
+
+
+
Oops, something went wrong.

0 comments on commit 439bab2

Please sign in to comment.