Start converting docs to Sphinx.

docs/.static/repoze.css

@@ -0,0 +1,22 @@
+@import url('default.css');
+body {
+    background-color: #006339;
+}
+ 
+div.document {
+    background-color: #dad3bd;
+}
+
+div.sphinxsidebar h3, h4, h5, a {
+    color: #127c56 !important;
+}
+
+div.related {
+    color: #dad3bd !important;
+    background-color: #00744a;
+}
+ 
+div.related a {
+    color: #dad3bd !important;
+}
+

docs/Makefile

@@ -0,0 +1,70 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview over all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+
+clean:
+	-rm -rf .build/*
+
+html:
+	mkdir -p .build/html .build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
+	@echo
+	@echo "Build finished. The HTML pages are in .build/html."
+
+pickle:
+	mkdir -p .build/pickle .build/doctrees
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files or run"
+	@echo "  sphinx-web .build/pickle"
+	@echo "to start the sphinx-web server."
+
+web: pickle
+
+htmlhelp:
+	mkdir -p .build/htmlhelp .build/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in .build/htmlhelp."
+
+latex:
+	mkdir -p .build/latex .build/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in .build/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	mkdir -p .build/changes .build/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
+	@echo
+	@echo "The overview file is in .build/changes."
+
+linkcheck:
+	mkdir -p .build/linkcheck .build/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in .build/linkcheck/output.txt."

docs/api.rst

@@ -0,0 +1,14 @@
+API Documentation for repoze.atemplate
+======================================
+
+Interfaces
+----------
+
+Document interfaces here.  You may want to use the ``.. autointerface::``
+directive provided by :mod:`repoze.sphinx.autointerface`, in which case
+you will need to add it to the extensions in `conf.py`.
+
+Exceptions
+----------
+
+Document any custom exceptions here.

docs/conf.py

@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+#
+# supervisor documentation build configuration file
+#
+# This file is execfile()d with the current directory set to its containing
+# dir.
+#
+# The contents of this file are pickled, so don't put values in the
+# namespace that aren't pickleable (module imports are okay, they're
+# removed automatically).
+#
+# All configuration values have a default value; values that are commented
+# out serve to show the default value.
+
+import sys, os
+
+# If your extensions are in another directory, add it here. If the
+# directory is relative to the documentation root, use os.path.abspath to
+# make it absolute, like shown here.
+#sys.path.append(os.path.abspath('some/directory'))
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'supervisor'
+copyright = '2004-2010, Agendaless Consulting <supervisor-users@lists.supervisord.org>'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '3.0a8'
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# There are two options for replacing |today|: either, you set today to
+# some non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directories, that shouldn't be
+# searched for source files.
+#exclude_dirs = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'repoze.css'
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as
+# html_title.
+#html_short_title = None
+
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+html_logo = '.static/logo_hi.gif'
+
+# The name of an image file (within the static path) to use as favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or
+# 32x32 pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets)
+# here, relative to this directory. They are copied after the builtin
+# static files, so a file named "default.css" will overwrite the builtin
+# "default.css".
+html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page
+# bottom, using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as
+# _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages
+# will contain a <link> tag referring to it.  The value of this option must
+# be the base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'atemplatedoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, document class [howto/manual]).
+latex_documents = [
+  ('index', 'supervisor.tex', 'supervisor Documentation',
+   'Supervisor Developers', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the
+# top of the title page.
+latex_logo = '.static/logo_hi.gif'
+
+# For "manual" documents, if this is true, then toplevel headings are
+# parts, not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True

docs/index.rst

@@ -0,0 +1,17 @@
+Supervisor: A Process Control System
+====================================
+
+``supervisor`` is a client/server system that allows its users to
+control a number of processes on UNIX-like operating systems.
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction.rst
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/introduction.rst

@@ -0,0 +1,170 @@
+Introduction
+============
+
+Overview
+--------
+
+``supervisor`` is a client/server system that allows its users to
+control a number of processes on UNIX-like operating systems.  It was
+inspired by the following:
+
+Convenience
+
+  It is often inconvenient to need to write ``rc.d`` scripts for every
+  single process instance.  ``rc.d`` scripts are a great
+  lowest-common-denominator form of process
+  initialization/autostart/management, but they can be painful to
+  write and maintain.  Additionally, ``rc.d`` scripts cannot
+  automatically restart a crashed process and many programs do not
+  restart themselves properly on a crash.  Supervisord starts
+  processes as its subprocesses, and can be configured to
+  automatically restart them on a crash.  It can also automatically be
+  configured to start processes on its own invocation.
+
+Accuracy
+
+  It's often difficult to get accurate up/down status on processes on
+  UNIX.  Pidfiles often lie.  Supervisord starts processes as
+  subprocesses, so it always knows the true up/down status of its
+  children and can be queried conveniently for this data.
+
+Delegation
+
+  Users who need to control process state often need only to do that.
+  They don't want or need full-blown shell access to the machine on
+  which the processes are running.  Processes which listen on "low"
+  TCP ports often need to be started and restarted as the root user (a
+  UNIX misfeature).  It's usually the case that it's perfectly fine to
+  allow "normal" people to stop or restart such a process, but
+  providing them with shell access is often impractical, and providing
+  them with root access or sudo access is often impossible.  It's also
+  (rightly) difficult to explain to them why this problem exists.  If
+  supervisord is started as root, it is possible to allow "normal"
+  users to control such processes without needing to explain the
+  intricacies of the problem to them.  Supervisorctl allows a very
+  limited form of access to the machine, essentially allowing users to
+  see process status and control supervisord-controlled subprocesses
+  by emitting "stop", "start", and "restart" commands from a simple
+  shell or web UI.
+
+Distributed Control
+
+  Users often need to control processes on many machines.  Supervisor
+  provides a simple, secure, and uniform mechanism for interactively
+  and automatically controlling processes on groups of machines.
+
+Process Groups
+      
+  Processes often need to be started and stopped in groups, sometimes
+  even in a "priority order".  It's often difficult to explain to
+  people how to do this.  Supervisor allows you to assign priorities
+  to processes, and allows user to emit commands via the supervisorctl
+  client like "start all", and "restart all", which starts them in the
+  preassigned priority order.  Additionally, processes can be grouped
+  into "process groups" and a set of logically related processes can
+  be stopped and started as a unit.  </para> </listitem>
+  </itemizedlist>
+
+Supervisor Components
+---------------------
+
+:program:`supervisord`
+
+  The server piece of supervisor is named :program:`supervisord`.  It
+  is responsible for starting child programs at its own invocation,
+  responding to commands from clients, restarting crashed or exited
+  subprocesseses, logging its subprocess ``stdout`` and ``stderr``
+  output, and generating and handling "events" corresponding to points
+  in subprocess lifetimes.
+
+  The server process uses a configuration file.  This is typically
+  located in :file:`/etc/supervisord.conf`.  This configuration file
+  is an "Windows-INI" style config file.  It is important to keep this
+  file secure via proper filesystem permissions because it may contain
+  unencrypted usernames and passwords.
+
+:program:`supervisorctl`
+      
+  The command-line client piece of the supervisor is named
+  :program:`supervisorctl`.  It provides a shell-like interface to the
+  features provided by :program:`supervisord`.  From
+  :program:`supervisorctl`, a user can connect to different
+  :program:`supervisord` processes, get status on the subprocesses
+  controlled by, stop and start subprocesses of, and get lists of
+  running processes of a :program:`supervisord`.
+          
+  The command-line client talks to the server across a UNIX domain
+  socket or an internet (TCP) socket.  The server can assert that the
+  user of a client should present authentication credentials before it
+  allows him to perform commands.  The client process typically uses
+  the same configuration file as the server but any configuration file
+  with a ``[supervisorctl]`` section in it will work.
+
+Web Server
+      
+  A (sparse) web user interface with functionality comparable to
+  :program:`supervisorctl` may be accessed via a browser if you start
+  :program:`supervisord` against an internet socket.  Visit the server
+  URL (e.g. ``http://localhost:9001/``) to view and control process
+  status through the web interface after activating the configuration
+  file's ``[inet_http_server]`` section.
+
+XML-RPC Interface
+
+  The same HTTP server which serves the web UI serves up an XML-RPC
+  interface that can be used to interrogate and control supervisor and
+  the programs it runs.  To use the XML-RPC interface, connect to
+  supervisor's http port with any XML-RPC client library and run
+  commands against it.  An example of doing this using Python's
+  ``xmlrpclib`` client library is as follows.
+
+  .. code-block:: python
+
+     import xmlrpclib
+     server = xmlrpclib.Server('http://localhost:9001')
+          
+  You may call methods against the :program:`supervisord` and its
+  subprocesses by using the ``supervisor`` namespace.  An example is
+  provided below.
+          
+  .. code-block:: python
+
+     server.supervisor.getState()
+
+  You can get a list of methods supported by the
+  :program:`supervisord` XML-RPC interface by using the XML-RPC
+  ``system.listMethods`` API:
+
+  .. code-block:: python
+          
+     server.system.listMethods()
+          
+  You can see help on a method by using the ``system.methodHelp`` API
+  against the method:
+
+  .. code-block:: python
+          
+     print server.system.methodHelp('supervisor.shutdown')
+
+  The :program:`supervisord` XML-RPC interface also supports the
+  nascent `XML-RPC multicall API
+  <http://www.xmlrpc.com/discuss/msgReader$1208>`_.
+          
+  You can extend :program:`supervisord` functionality with new XML-RPC
+  API methods by adding new top-level RPC interfaces as necessary.
+  See :ref:`rpcinterface_settings`.
+
+Platform Requirements
+---------------------
+
+Supervisor has been tested and is known to run on Linux (Ubuntu
+Dapper/Feisy/Gutsy), Mac OS X (10.4/10.5), and Solaris (10 for Intel)
+and FreeBSD 6.1.  It will likely work fine on most UNIX systems.
+      
+Supervisor will not run at all under any version of Windows.
+
+Supervisor is known to work with Python 2.3.3 or better, and it may
+work with Python 2.3.0, Python 2.3.1 and Python 2.3.2 (although these
+have not been tested).  It will not work at all with Python versions
+before 2.3.0.  Supervisor is not compatible with Python 3.X.
+