add xmlrpc and upgrading chapters

docs/index.rst

@@ -27,6 +27,8 @@ Narrative Documentation
    subprocess.rst
    logging.rst
    events.rst
+   xmlrpc.rst
+   upgrading.rst
 
 API Documentation
 -----------------

docs/upgrading.rst

@@ -0,0 +1,62 @@
+Upgrading Supervisor 2 to 3
+===========================
+
+The following is true when upgrading an installation from Supervisor
+2.X to Supervisor 3.X:
+
+#.  In ``[program:x]`` sections, the keys ``logfile``,
+    ``logfile_backups``, ``logfile_maxbytes``, ``log_stderr`` and
+    ``log_stdout`` are no longer valid.  Supervisor2 logged both
+    stderr and stdout to a single log file.  Supervisor 3 logs stderr
+    and stdout to separate log files.  You'll need to rename
+    ``logfile`` to ``stdout_logfile``, ``logfile_backups`` to
+    ``stdout_logfile_backups``, and ``logfile_maxbytes`` to
+    ``stdout_logfile_maxbytes`` at the very least to preserve your
+    configuration.  If you created program sections where
+    ``log_stderr`` was true, to preserve the behavior of sending
+    stderr output to the stdout log, use the ``redirect_stderr``
+    boolean in the program section instead.
+
+#.  The supervisor configuration file must include the following
+    section verbatim for the XML-RPC interface (and thus the web
+    interface and :program:`supervisorctl`) to work properly:
+
+    .. code-block:: ini
+
+       [rpcinterface:supervisor]
+       supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
+
+#.  The semantics of the ``autorestart`` parameter within
+    ``[program:x]`` sections has changed.  This parameter used to
+    accept only ``true`` or ``false``.  It now accepts an additional
+    value, ``unexpected``, which indicates that the process should
+    restart from the ``EXITED`` state only if its exit code does not
+    match any of those represented by the ``exitcode`` parameter in
+    the process' configuration (implying a process crash).  In
+    addition, the default for ``autorestart`` is now ``unexpected``
+    (it used to be ``true``, which meant restart unconditionally).
+
+#.  We now allow :program:`supervisord` to listen on both a UNIX
+    domain socket and an inet socket instead of making listening on
+    one mutually exclusive with listening on the other.  As a result,
+    the options ``http_port``, ``http_username``, ``http_password``,
+    ``sockchmod`` and ``sockchown`` are no longer part of
+    the ``[supervisord]`` section configuration. These have been
+    supplanted by two other sections: ``[unix_http_server]`` and
+    ``[inet_http_server]``.  You'll need to insert one or the other
+    (depending on whether you want to listen on a UNIX domain socket
+    or a TCP socket respectively) or both into your
+    :file:`supervisord.conf` file.  These sections have their own
+    options (where applicable) for ``port``, ``username``,
+    ``password``, ``chmod``, and ``chown``.
+
+#.  All supervisord command-line options related to ``http_port``,
+    ``http_username``, ``http_password``, ``sockchmod`` and
+    ``sockchown`` have been removed (see above point for rationale).
+
+#. The option that used to be ``sockchown`` within the
+   ``[supervisord]`` section (and is now named ``chown`` within the
+   ``[unix_http_server]`` section) used to accept a dot-separated
+   (``user.group``) value.  The separator now must be a
+   colon, e.g. ``user:group``.  Unices allow for dots in
+   usernames, so this change is a bugfix.

docs/xmlrpc.rst

@@ -0,0 +1,58 @@
+Extending Supervisor's XML-RPC API
+==================================
+
+Supervisor can be extended with new XML-RPC APIs.  Several third-party
+plugins already exist that can be wired into your Supervisor
+configuration.  You may additionally write your own.  Extensible
+XML-RPC interfaces is an advanced feature, introduced in version 3.0.
+You needn't understand it unless you wish to use an existing
+third-party RPC interface plugin or if you wish to write your own RPC
+interface plugin.
+
+Configuring XML-RPC Interface Factories
+---------------------------------------
+
+An additional RPC interface is configured into a supervisor
+installation by adding a ``[rpcinterface:x]`` section in the
+Supervisor configuration file.
+
+In the sample config file, there is a section which is named
+``[rpcinterface:supervisor]``.  By default it looks like this:
+
+.. code-block:: ini
+    
+   [rpcinterface:supervisor]
+   supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
+
+This section *must* remain in the configuration for the standard setup
+of supervisor to work properly.  If you don't want supervisor to do
+anything it doesn't already do out of the box, this is all you need to
+know about this type of section.
+
+However, if you wish to add additional XML-RPC interface namespaces to
+a configuration of supervisor, you may add additional
+``[rpcinterface:foo]`` sections, where "foo" represents the namespace
+of the interface (from the web root), and the value named by
+``supervisor.rpcinterface_factory`` is a factory callable written in
+Python which should have a function signature that accepts a single
+positional argument ``supervisord`` and as many keyword arguments as
+required to perform configuration.  Any key/value pairs defined within
+the ``rpcinterface:foo`` section will be passed as keyword arguments
+to the factory.  Here's an example of a factory function, created in
+the package ``my.package``.
+
+.. code-block:: python
+
+   def make_another_rpcinterface(supervisord, **config):
+       retries = int(config.get('retries', 0))
+       another_rpc_interface = AnotherRPCInterface(supervisord, retries)
+       return another_rpc_interface
+
+And a section in the config file meant to configure it.
+
+.. code-block:: ini
+
+   [rpcinterface:another]
+   supervisor.rpcinterface_factory = my.package:make_another_rpcinterface
+   retries = 1
+