Patch #536883: SimpleXMLRPCServer auto-docing subclass.

3 files changed, 114 insertions, 0 deletions

diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 5faeedc..3843d46 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -231,6 +231,7 @@ and how to embed it in other applications.
 \input{libcookie}
 \input{libxmlrpclib}
 \input{libsimplexmlrpc}
+\input{libdocxmlrpc}
 \input{libasyncore}
 \input{libasynchat}
 
diff --git a/Doc/lib/libdocxmlrpc.tex b/Doc/lib/libdocxmlrpc.tex
new file mode 100644
index 0000000..fc69031
--- /dev/null
+++ b/Doc/lib/libdocxmlrpc.tex
@@ -0,0 +1,105 @@
+\section{\module{DocXMLRPCServer} ---
+         Self-documenting XML-RPC server}
+
+\declaremodule{standard}{DocXMLRPCServer}
+\modulesynopsis{Self-documenting XML-RPC server implementation.}
+\moduleauthor{Brian Quinlan}{brianq@activestate.com}
+\sectionauthor{Brian Quinlan}{brianq@activestate.com}
+
+\versionadded{2.3}
+
+The \module{DocXMLRPCServer} module extends the classes found in
+\module{SimpleXMLRPCServer} to serve HTML documentation in response to
+HTTP GET requests. Servers can either be free standing, using
+\class{DocXMLRPCServer}, or embedded in a CGI environment, using
+\class{DocCGIXMLRPCRequestHandler}.
+
+\begin{classdesc}{DocXMLRPCServer}{addr\optional{, 
+                                   requestHandler\optional{, logRequests}}}
+
+Create a new server instance. All parameters have the same meaning as
+for \class{SimpleXMLRPCServer.SimpleXMLRPCServer};
+\var{requestHandler} defaults to \class{DocXMLRPCRequestHandler}.
+
+\end{classdesc}
+
+\begin{classdesc}{DocCGIXMLRPCRequestHandler}{}
+
+Create a new instance to handle XML-RPC requests in a CGI environment.
+
+\end{classdesc}
+
+\begin{classdesc}{DocXMLRPCRequestHandler}{}
+
+Create a new request handler instance. This request handler supports
+XML-RPC POST requests, documentation GET requests, and modifies
+logging so that the \var{logRequests} parameter to the
+\class{DocXMLRPCServer} constructor parameter is honored.
+
+\end{classdesc}
+
+\subsection{DocXMLRPCServer Objects \label{doc-xmlrpc-servers}}
+
+The \class{DocXMLRPCServer} class is derived from
+\class{SimpleXMLRPCServer.SimpleXMLRPCServer} and provides a means of
+creating self-documenting, stand alone XML-RPC servers. HTTP POST
+requests are handled as XML-RPC method calls. HTTP GET requests are
+handled by generating pydoc-style HTML documentation. This allows a
+server to provide its own web-based documentation.
+
+\begin{methoddesc}{set_server_title}{server_title}
+
+Set the title used in the generated HTML documentation. This title
+will be used inside the HTML "title" element.
+
+\end{methoddesc}
+
+\begin{set_server_name}{server_name}
+
+Set the name used in the generated HTML documentation. This name will
+appear at the top of the generated documentation inside a "h1"
+element.
+
+\end{methoddesc}
+
+
+\begin{set_server_documentation}{server_documentation}
+
+Set the description used in the generated HTML documentation. This
+description will appear as a paragraph, below the server name, in the
+documentation.
+
+\end{methoddesc}
+
+\subsection{DocCGIXMLRPCRequestHandler}
+
+The \class{DocCGIXMLRPCRequestHandler} class is derived from
+\class{SimpleXMLRPCServer.CGIXMLRPCRequestHandler} and provides a means
+of creating self-documenting, XML-RPC CGI scripts. HTTP POST requests
+are handled as XML-RPC method calls. HTTP GET requests are handled by
+generating pydoc-style HTML documentation. This allows a server to
+provide its own web-based documentation.
+
+\begin{methoddesc}{set_server_title}{server_title}
+
+Set the title used in the generated HTML documentation. This title
+will be used inside the HTML "title" element.
+
+\end{methoddesc}
+
+\begin{methoddesc}{set_server_name}{server_name}
+
+Set the name used in the generated HTML documentation. This name will
+appear at the top of the generated documentation inside a "h1"
+element.
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{set_server_documentation}{server_documentation}
+
+Set the description used in the generated HTML documentation. This
+description will appear as a paragraph, below the server name, in the
+documentation.
+
+\end{methoddesc}
diff --git a/Doc/whatsnew/whatsnew23.tex b/Doc/whatsnew/whatsnew23.tex
index 38669b2..f447ed4 100644
--- a/Doc/whatsnew/whatsnew23.tex
+++ b/Doc/whatsnew/whatsnew23.tex
@@ -1812,6 +1812,14 @@ of the URL is ASCII only.
 To implement this change, the module \module{stringprep}, the tool
 \code{mkstringprep} and the \code{punycode} encoding have been added.
 
+\item The new \module{DocXMLRPCServer} allows to write 
+self-documenting XML-RPC servers. Run it in demo mode (as a program)
+to see it in action: Pointing the Web browser to the RPC server
+produces pydoc-style documentation; pointing xmlrpclib to the
+server allows to invoke the actual methods.
+
+Contributed by Brian Quinlan.
+
 \end{itemize}