OLD | NEW |
---|---|
(Empty) | |
1 doxypypy | |
2 ======== | |
3 | |
4 *A more Pythonic version of doxypy, a Doxygen filter for Python.* | |
5 | |
6 Intent | |
7 ------ | |
8 | |
9 For now Doxygen_ has limited support for Python. It recognizes Python comments, | |
10 but otherwise treats the language as being more or less like Java. It doesn't | |
11 understand basic Python syntax constructs like docstrings, keyword arguments, | |
12 generators, nested functions, decorators, or lambda expressions. It likewise | |
13 doesn't understand conventional constructs like doctests or ZOPE-style | |
14 interfaces. It does however support inline filters that can be used to make | |
15 input source code a little more like what it's expecting. | |
16 | |
17 The excellent doxypy_ makes it possible to embed Doxygen commands in Python | |
18 docstrings, and have those docstrings converted to Doxygen-recognized comments | |
19 on the fly per Doxygen's regular input filtering process. It however does not | |
20 address any of the other previously mentioned areas of difficulty. | |
21 | |
22 This project started off as a fork of doxypy but quickly became quite distinct. | |
23 It shares little (if any) of the same code at this point (but maintains the | |
24 original license just in case). It is meant to support all the same command | |
25 line options as doxypy, but handle additional Python syntax beyond docstrings. | |
26 | |
27 Additional Syntax Supported | |
28 --------------------------- | |
29 | |
30 Python can have functions and classes within both functions and classes. | |
31 Doxygen best understands this concept via its notion of namespaces. This filter | |
32 thus can supply Doxygen tags marking namespaces on every function and class. | |
33 This addresses the issue of Doxygen merging inner functions' documentation with | |
34 the documentation of the parent. | |
35 | |
36 Python class members whose names begin with a double-underscore are mangled | |
37 and kept private by the language. Doxygen does not understand this natively | |
38 yet, so this filter additionally provides Doxygen tags to label such variables | |
39 as private. | |
40 | |
41 Python frequently embeds doctests within docstrings. This filter makes it | |
42 trivial to mark off such sections of the docstring so they get displayed as | |
43 code. | |
44 | |
45 ZOPE-style interfaces overload class definitions to be interface definitions, | |
46 use embedded variable assignments to identify attributes, and use specific | |
47 function calls to indicate interface adherence. Furthermore, they frequently | |
48 don't have any code beyond their docstrings, so naively removing docstrings | |
49 would result in broken Python. This filter has basic understanding of these | |
50 interfaces and treats them accordingly, supplying Doxygen tags as appropriate. | |
51 | |
52 Fundamentally Python docstrings are meant for humans and not machines, and ought | |
53 not to have special mark-up beyond conventional structured text. This filter | |
54 heuristically examines Python docstrings, and ones like the sample for complex | |
55 in `PEP 257`_ or that generally follow the stricter `Google Python Style Guide`_ | |
56 will get appropriate Doxygen tags automatically added. | |
57 | |
58 How It Works | |
59 ------------ | |
60 | |
61 This project takes a radically different approach than doxypy. Rather than use | |
62 regular expressions tied to a state machine to figure out syntax, Python's own | |
63 Abstract Syntax Tree module is used to extract items of interest. If the | |
64 `autobrief` option is enabled, docstrings are parsed via a set of regular | |
65 expressions and a producer / consumer pair of coroutines. | |
66 | |
67 Example | |
68 ------- | |
69 | |
70 This filter will correctly process code like the following working (albeit | |
71 contrived) example: | |
72 | |
73 .. code-block:: python | |
74 | |
75 def myfunction(arg1, arg2, kwarg='whatever.'): | |
76 """ | |
77 Does nothing more than demonstrate syntax. | |
78 | |
79 This is an example of how a Pythonic human-readable docstring can | |
80 get parsed by doxypypy and marked up with Doxygen commands as a | |
81 regular input filter to Doxygen. | |
82 | |
83 Args: | |
84 arg1: A positional argument. | |
85 arg2: Another positional argument. | |
86 | |
87 Kwargs: | |
88 kwarg: A keyword argument. | |
89 | |
90 Returns: | |
91 A string holding the result. | |
92 | |
93 Raises: | |
94 ZeroDivisionError, AssertionError, & ValueError. | |
95 | |
96 Examples: | |
97 >>> myfunction(2, 3) | |
98 '5 - 0, whatever.' | |
99 >>> myfunction(5, 0, 'oops.') | |
100 Traceback (most recent call last): | |
101 ... | |
102 ZeroDivisionError: integer division or modulo by zero | |
103 >>> myfunction(4, 1, 'got it.') | |
104 '5 - 4, got it.' | |
105 >>> myfunction(23.5, 23, 'oh well.') | |
106 Traceback (most recent call last): | |
107 ... | |
108 AssertionError | |
109 >>> myfunction(5, 50, 'too big.') | |
110 Traceback (most recent call last): | |
111 ... | |
112 ValueError | |
113 """ | |
114 assert isinstance(arg1, int) | |
115 if arg2 > 23: | |
116 raise ValueError | |
117 return '{0} - {1}, {2}'.format(arg1 + arg2, arg1 / arg2, kwarg) | |
118 | |
119 There are a few points to note: | |
120 | |
121 1. No special tags are used. Best practice human-readable section headers | |
122 are enough. | |
123 | |
124 2. Some flexibility is allowed. Most common names for sections are accepted, | |
125 and items and descriptions may be separated by either colons or dashes. | |
126 | |
127 3. The brief must be the first item and be no longer than one line. | |
128 | |
129 4. Everything thrown into an examples section will be treated as code, so it's | |
130 the perfect place for doctests. | |
131 | |
132 Additional more comprehensive examples can be found in the test area. | |
133 | |
134 Previewing doxypypy Output | |
135 -------------------------- | |
136 | |
137 After successful installation, doxypypy can be run from the command line to | |
138 preview the filtered results with: | |
139 | |
140 .. code-block:: shell | |
141 | |
142 python -m doxypypy.doxypypy -a -c file.py | |
143 | |
144 Typically you'll want to redirect output to a file for viewing in a text editor: | |
145 | |
146 .. code-block:: shell | |
147 | |
148 python -m doxypypy.doxypypy -a -c file.py > file.py.out | |
149 | |
150 Invoking doxypypy from Doxygen | |
151 ------------------------------ | |
152 | |
153 To make Doxygen run your Python code through doxypypy, set the FILTER\_PATTERNS | |
154 tag in your Doxyfile as follows: | |
155 | |
156 .. code-block:: shell | |
157 | |
158 FILTER_PATTERNS = *.py=py_filter | |
159 | |
160 `py_filter` must be available in your path as a shell script (or Windows batch | |
161 file). If you wish to run `py_filter` in a particular directory you can include | |
162 the full or relative path. | |
163 | |
164 For Unix-like operating systems, `py_filter` should like something like this: | |
165 | |
166 .. code-block:: shell | |
167 | |
168 #!/bin/bash | |
169 python -m doxypypy.doxypypy -a -c $1 | |
170 | |
171 In Windows, the batch file should be named `py_filter.bat`, and need only | |
172 contain the one line: | |
173 | |
174 .. code-block:: shell | |
175 | |
176 python -m doxypypy.doxypypy -a -c %1 | |
177 | |
178 Running Doxygen as usual should now run all Python code through doxypypy. Be | |
179 sure to carefully browse the Doxygen output the first time to make sure that | |
180 Doxygen properly found and executed doxypypy. | |
181 | |
182 .. _Doxygen: http://www.stack.nl/~dimitri/doxygen/ | |
183 .. _doxypy: https://github.com/Feneric/doxypy | |
184 .. _PEP 257: http://www.python.org/dev/peps/pep-0257/ | |
Jim Stichnoth
2016/01/11 14:44:46
use https
rkotlerimgtec
2016/01/11 21:06:06
Done.
| |
185 .. _Google Python Style Guide: http://google-styleguide.googlecode.com/svn/trunk /pyguide.html?showone=Comments#Comments | |
Jim Stichnoth
2016/01/11 14:44:46
This link is broken (plus it's not https).
rkotlerimgtec
2016/01/11 21:06:06
Done.
| |
186 | |
Jim Stichnoth
2016/01/11 14:44:46
Trailing whitespace.
rkotlerimgtec
2016/01/11 21:06:06
Done.
| |
OLD | NEW |