PureDocs

source: trunk/doc/README.txt @ 154

Revision 154, 6.4 KB checked in by will, 5 years ago (diff)

Rename README to have a file extension. I like extensions.
Line 
1PureDocs
2Version 0.2
3
4About PureDocs
5
6        What is PureDocs?
7
8                PureDocs is system for API documentation generation. It provides
9                a system for pluggable language support and output support. The
10                default preference is for ReStructured Text ouptut to a custom
11                XML format which can then be transformed in to the desired
12                XHTML, or other final form
13
14        Why Another API Doc System?
15
16                A couple of reasons, first being that most api documentation
17                generation systems prefer a single output format, without any
18                options for intermediate forms. In addition, most use a method
19                of regular expression matching to "guess" the syntax of
20                languages they support. They also tend to prefer a specific set
21                of keywords or declarations that are immutable, regardless of
22                their relevence to the language in question.
23
24                PureDocs is designed around three components:
25
26                * The Language Parser
27                * The Output Writer
28                * The XSL Transformer (Optional)
29
30                The Language parser is responsible for actually parsing the
31                language and extracting the tokens and documentation strings
32                that will be used for generating the API documentation. This is
33                a plugin associated with the mine type of a language's source
34                file. It then generates a tree of generic PureDocs "Resource"
35                objects which are passed off the the Output Writer.
36
37                The Output Writer takes a tree of Resource objects and generates
38                the requested output. The preferences is for XML output. The
39                Output processor parses the documentation strings of the
40                Resource object, putting the documentation in context with the
41                appropriate tokens extracted along with the documentation
42                strings.
43
44                The XSL Transformer is optional, obviously depending on whether
45                the Ouptut Writer outputs XML. This is external to PureDocs, and
46                can be used to associate packages together, dependencies, etc,
47                between nodes in the XML trees.
48
49                PureDocs ships with a Python language plugin and a ReStructured
50                Text documentation strings plugin.
51
52        What if I use [Other Doc System]?
53
54                PureDocs is designed so that Output Writers can be written that
55                support any other documentation system's keywords or
56                declarations. One can write an output processor that parses the
57                documentation string in the comment in any way wished.
58
59                For example, an output plugin that supports JavaDoc declarations
60                could easily be written, parsing the extracted comment for those
61                declarations. This would, of course, require a Java language
62                plugin as well.
63
64Requirements
65
66        PureDocs depends on the following other software packages before it
67        can be used.  The given version numbers are minimums, and versions
68        greater than those listed should work.  Please see the listed urls
69        for more information about each, as well as installation
70        instructions and troubleshooting.
71
72        * Python >= 2.4
73                - http://www.python.org
74        * Docutils >= 0.4
75                - http://docutils.sourceforge.net
76                - Only required for the ReStructuredText Output Writer plugin
77        * Twisted Core >= 2.4
78                - http://twistedmatrix.com
79                - Earlier versions will probably work, but haven't been tested
80        * ZopeInterface >= 3.0
81                - http://www.zope.org/Products/ZopeInterface
82        * lxml >= 1.0
83                - http://codespeak.net/lxml/
84                - Earlier versions will probably work, but haven't been tested
85        * setuptools >= 0.6
86                - http://peak.telecommunity.com/DevCenter/setuptools
87
88Installing
89       
90        To install PureDocs, run some form of the following command:
91               
92                python setup.py install
93
94        From the base directory of the source tree.
95
96        If you're interested in developing PureDocs (this does NOT include
97        plugins), you could also do the following:
98
99                python setup.py develop
100
101        Which installs the package as a symbolic link, including the
102        command-line utility so that you can continue working from your
103        current directory.  See the setuptools document for more
104        information:
105
106                http://peak.telecommunity.com/DevCenter/setuptools
107
108Plugin API
109
110        For plugins, PureDocs utilizes the setuptools package from peak.org.
111        This allows for plugin authors to create Python packages containing
112        their plugins, and simply declare their entry points in the setup.py
113        file for that plugin.  For more information on setuptools and entry
114        points, see:
115
116        http://peak.telecommunity.com/DevCenter/setuptools#entry-points
117
118        Language Parser
119
120                The Language Parser plugin's entry point should corrospond to
121                the mime type of the files containing the given language's code.
122
123                Whether it is a single class, or a module, it should provide
124                access to two object:
125
126                        parser
127                        options
128
129                The parser object should be a class that takes a filename
130                (including path) as the argument to its __init__ method, parses
131                the     given file, and provides access to a 'root' attribute.  The
132                'root' attribute should be a Resource object, containing other
133                Resource objects that make up the tree of documentable items
134                that resulted from parsing.
135
136                For more information about the parser interface, see
137                puredocs/interfaces/language.py.
138               
139                The options object is detailed below.
140
141        Output Writer
142
143                The Output Writer plugin's entry point should corrospond to the
144                name of the output format, for example, 'xml'.  It may also
145                chose to differentiate itself from other similar output formats.
146                The only place this is used is by the user at the comment line
147                in specifying the format they wish.
148
149                As with the Language Parser, the Output Writer's entry point
150                should corrospond to an object (a module or class) with objects:
151
152                        writer
153                        options
154
155                The writer object should be a class that takes a Resource object
156                as the argument to its __init__ method, and generates output
157                from that Resource object and recursively through any children
158                it might have.
159
160                The writer class should provide two methods, 'string', and
161                'write'.  The string method will return a string representation
162                of the output, while the write method will take an arguement for
163                its destination and output to that location.
164
165                The Output Writer is responsible for processing documentation
166                associated with each Resource by the parser, in whatever way it
167                may see fit.
168
169                For more information about the writer interface, see
170                puredocs/interfaces/output.py.
171
172                The options object is detailed below.
173
174        Options
175
176                Command-line arguments can be accepted by any plugin,
177                independent of PureDocs.  These arguments are specified by the
178                plugin's 'options' object.  This should be a class subclassing
179                puredocs.Options, which is imported from twisted.python.usage.
180
181                For more information about Options classes, see:
182
183                http://twistedmatrix.com/projects/core/documentation/howto/options.html
Note: See TracBrowser for help on using the repository browser.