Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(144)

Side by Side Diff: doxypypy/README.rst

Issue 1574883002: add doxypypy and py_filter so this will turn google style (Closed) Base URL: https://chromium.googlesource.com/native_client/pnacl-subzero.git@master
Patch Set: Created 4 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
(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.
OLDNEW
« doxypypy/.gitignore ('K') | « doxypypy/MANIFEST.in ('k') | doxypypy/doxypypy/__init__.py » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698