| 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 |
|