1:mod:`DocXMLRPCServer` --- Self-documenting XML-RPC server
2==========================================================
3
4.. module:: DocXMLRPCServer
5   :synopsis: Self-documenting XML-RPC server implementation.
6.. moduleauthor:: Brian Quinlan <brianq@activestate.com>
7.. sectionauthor:: Brian Quinlan <brianq@activestate.com>
8
9.. note::
10   The :mod:`DocXMLRPCServer` module has been merged into :mod:`xmlrpc.server`
11   in Python 3.  The :term:`2to3` tool will automatically adapt imports when
12   converting your sources to Python 3.
13
14
15.. versionadded:: 2.3
16
17The :mod:`DocXMLRPCServer` module extends the classes found in
18:mod:`SimpleXMLRPCServer` to serve HTML documentation in response to HTTP GET
19requests. Servers can either be free standing, using :class:`~DocXMLRPCServer.DocXMLRPCServer`,
20or embedded in a CGI environment, using :class:`DocCGIXMLRPCRequestHandler`.
21
22
23.. class:: DocXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[,  encoding[, bind_and_activate]]]]])
24
25   Create a new server instance. All parameters have the same meaning as for
26   :class:`SimpleXMLRPCServer.SimpleXMLRPCServer`; *requestHandler* defaults to
27   :class:`DocXMLRPCRequestHandler`.
28
29
30.. class:: DocCGIXMLRPCRequestHandler()
31
32   Create a new instance to handle XML-RPC requests in a CGI environment.
33
34
35.. class:: DocXMLRPCRequestHandler()
36
37   Create a new request handler instance. This request handler supports XML-RPC
38   POST requests, documentation GET requests, and modifies logging so that the
39   *logRequests* parameter to the :class:`~DocXMLRPCServer.DocXMLRPCServer` constructor parameter is
40   honored.
41
42
43.. _doc-xmlrpc-servers:
44
45DocXMLRPCServer Objects
46-----------------------
47
48The :class:`~DocXMLRPCServer.DocXMLRPCServer` class is derived from
49:class:`SimpleXMLRPCServer.SimpleXMLRPCServer` and provides a means of creating
50self-documenting, stand alone XML-RPC servers. HTTP POST requests are handled as
51XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
52HTML documentation. This allows a server to provide its own web-based
53documentation.
54
55
56.. method:: DocXMLRPCServer.set_server_title(server_title)
57
58   Set the title used in the generated HTML documentation. This title will be used
59   inside the HTML "title" element.
60
61
62.. method:: DocXMLRPCServer.set_server_name(server_name)
63
64   Set the name used in the generated HTML documentation. This name will appear at
65   the top of the generated documentation inside a "h1" element.
66
67
68.. method:: DocXMLRPCServer.set_server_documentation(server_documentation)
69
70   Set the description used in the generated HTML documentation. This description
71   will appear as a paragraph, below the server name, in the documentation.
72
73
74DocCGIXMLRPCRequestHandler
75--------------------------
76
77The :class:`DocCGIXMLRPCRequestHandler` class is derived from
78:class:`SimpleXMLRPCServer.CGIXMLRPCRequestHandler` and provides a means of
79creating self-documenting, XML-RPC CGI scripts. HTTP POST requests are handled
80as XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
81HTML documentation. This allows a server to provide its own web-based
82documentation.
83
84
85.. method:: DocCGIXMLRPCRequestHandler.set_server_title(server_title)
86
87   Set the title used in the generated HTML documentation. This title will be used
88   inside the HTML "title" element.
89
90
91.. method:: DocCGIXMLRPCRequestHandler.set_server_name(server_name)
92
93   Set the name used in the generated HTML documentation. This name will appear at
94   the top of the generated documentation inside a "h1" element.
95
96
97.. method:: DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)
98
99   Set the description used in the generated HTML documentation. This description
100   will appear as a paragraph, below the server name, in the documentation.
101
102