earl · redhat-raptor · Jul 4, 2011 · Jul 4, 2011 · Jul 4, 2011 · Jul 4, 2011
diff --git a/README.mkd b/README.mkd
@@ -32,7 +32,7 @@ Here is a short example, to illustrate the flavor of beanstalkc:
 For more information, see [the tutorial][tutorial], which will explain most
 everything.
 
-[tutorial]: TUTORIAL.mkd
+[tutorial]: doc/TUTORIAL.rst
 
 
 License

diff --git a/beanstalkc.py b/beanstalkc.py
@@ -289,7 +289,7 @@ def stats(self):
         pid = os.spawnlp(os.P_NOWAIT,
                          'beanstalkd',
                          'beanstalkd', '-l', '127.0.0.1', '-p', '14711')
-        doctest.testfile('TUTORIAL.mkd', optionflags=doctest.ELLIPSIS)
+        doctest.testfile('doc/tutorial.rst', optionflags=doctest.ELLIPSIS)
         doctest.testfile('test/no-yaml.doctest', optionflags=doctest.ELLIPSIS)
     finally:
         os.kill(pid, signal.SIGTERM)
diff --git a/doc/Makefile b/doc/Makefile
@@ -0,0 +1,130 @@
+# 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) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+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 "  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/beanstalkc.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/beanstalkc.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/beanstalkc"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/beanstalkc"
+	@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."
+
+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."
diff --git a/doc/_templates/donations.html b/doc/_templates/donations.html
@@ -0,0 +1,7 @@
+<h3>Donate</h3>
+<ul>
+  <li>
+    <a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="http://github.com/earl/beanstalkc"></a>
+    <noscript><a href="http://flattr.com/thing/156111/beanstalkc" target="_blank"><img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0" /></a></noscript>
+  </li>
+</ul>
diff --git a/doc/_templates/searchbox.html b/doc/_templates/searchbox.html
@@ -0,0 +1,48 @@
+{#
+    basic/searchbox.html
+    ~~~~~~~~~~~~~~~~~~~~
+
+    Sphinx sidebar template: quick search box.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{#
+    Customised to show an additional "Donate" sidebar section below the search
+    box on "Read the Docs"-hosted documentation.
+#}
+{%- if pagename != "search" %}
+<div id="searchbox" style="display: none">
+  <h3>{{ _('Quick search') }}</h3>
+    <form class="search" action="{{ pathto('search') }}" method="get">
+      <input type="text" name="q" size="18" />
+      <input type="submit" value="{{ _('Go') }}" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    <p class="searchtip" style="font-size: 90%">
+    {{ _('Enter search terms or a module, class or function name.') }}
+    </p>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+{%- endif %}
+
+{# -- #}
+<script type="text/javascript">
+  /* <![CDATA[ */
+  (function() {
+    var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
+    s.type = 'text/javascript';
+    s.async = true;
+    s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
+    t.parentNode.insertBefore(s, t);
+  })();
+  /* ]]> */
+</script>
+<h3>Donate</h3>
+<ul>
+  <li>
+    <a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="http://github.com/earl/beanstalkc"></a>
+    <noscript><a href="http://flattr.com/thing/156111/beanstalkc" target="_blank"><img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0" /></a></noscript>
+  </li>
+</ul>
diff --git a/doc/conf.py b/doc/conf.py
@@ -0,0 +1,61 @@
+# -*- coding: utf-8 -*-
+#
+import sys, os
+sys.path.insert(0, os.path.abspath('..'))
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+project = u'beanstalkc'
+copyright = u'2011, Andreas Bolka'
+version = '0.3'
+release = '0.3'
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.viewcode',
+]
+
+# -- Options for HTML output ---------------------------------------------------
+
+html_theme = 'nature'
+if on_rtd:
+    html_theme = 'default'
+#html_last_updated_fmt = '%Y-%m-%d'
+html_use_smartypants = True
+html_sidebars = {
+    '**': [
+        'localtoc.html',
+        'relations.html',
+        'sourcelink.html',
+        'searchbox.html',
+    ]
+}
+
+htmlhelp_basename = 'beanstalkcdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_paper_size = 'a4'
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('tutorial', 'beanstalkc.tex',
+   u'beanstalkc Tutorial', u'Andreas Bolka',
+   'howto'),
+]
+
+
+# -- Options for Epub output ---------------------------------------------------
+
+epub_title = u'beanstalkc Documentation'
+epub_author = u'Andreas Bolka'
+epub_publisher = u'Andreas Bolka'
+epub_copyright = u'2011, Andreas Bolka'
diff --git a/doc/index.rst b/doc/index.rst
@@ -0,0 +1,63 @@
+beanstalkc
+==========
+
+:mod:`beanstalkc` is a simple beanstalkd client library for Python.
+`beanstalkd`_ is a simple, fast work queue service.
+
+beanstalkc depends on `PyYAML`_, but there are ways to avoid this dependency.
+See :ref:`Appendix A <tut-appendix-a>` of the tutorial for details.
+
+beanstalkc is pure Python, and is compatible with `eventlet`_ and `gevent`_.
+
+.. _beanstalkd: http://kr.github.com/beanstalkd/
+.. _PyYAML: http://pyyaml.org/
+.. _eventlet: http://eventlet.net/
+.. _gevent: http://www.gevent.org/
+
+
+Contents
+========
+
+.. toctree::
+    :maxdepth: 2
+
+    tutorial
+    reference
+
+
+Usage
+=====
+
+Here is a short example, to illustrate the flavour of :mod:`beanstalkc`::
+
+    >>> import beanstalkc
+    >>> beanstalk = beanstalkc.Connection(host='localhost', port=11300)
+    >>> beanstalk.put('hey!')
+    1
+    >>> job = beanstalk.reserve()
+    >>> job.body
+    'hey!'
+    >>> job.delete() 
+
+
+License
+=======
+
+.. _Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
+
+Copyright © 2008-2011, Andreas Bolka. Licensed under the `Apache License,
+Version 2.0`_::
+
+    Copyright 2008-2011 Andreas Bolka
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an "AS
+    IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+    express or implied. See the License for the specific language
+    governing permissions and limitations under the License.
diff --git a/doc/reference.rst b/doc/reference.rst
@@ -0,0 +1,29 @@
+Reference
+=========
+
+.. automodule:: beanstalkc
+    :members:
+
+
+Core Classes
+------------
+
+.. autoclass:: Connection
+    :members:
+
+.. autoclass:: Job
+    :members:
+
+
+Exceptions
+----------
+
+.. autoclass:: BeanstalkcException
+
+.. autoclass:: UnexpectedResponse
+
+.. autoclass:: CommandFailed
+
+.. autoclass:: DeadlineSoon
+
+.. autoclass:: SocketError