Debian Codegraph @

doxypypy.egg-info/PKG-INFO

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