feneric / doxypypy Goto Github PK
View Code? Open in Web Editor NEWA more Pythonic version of doxypy, a Doxygen filter for Python.
License: GNU General Public License v2.0
A more Pythonic version of doxypy, a Doxygen filter for Python.
License: GNU General Public License v2.0
Where are the instructions/code on how to test?
I have seen no mention of it in the README, no CODING file, setup.py does not seem to contain anything related, no .travis.yml, shippable.yml, Makefile, or anything like that.
Running unittest with discovery fails.
Running PYTHONPATH=. ./doxypypy/test/test_doxypypy.py
fails a lot of tests with AttributeError: 'Options' object has no attribute 'object_respect'
It seems that doxypypy
can parse the Google docstring style well. What about numpy
style? I think this style should also be recognized as it's one of the most common styles, used by many in the scientific community.
Sorry for asking via GitHub Issues what is IMO only a tracker for bugs and feature requests. I could not find any contact to ask questions about doxypypy.
I know the this way to add informations about data type of function parameters in the doc string.
def foobar(param):
"""Short descript.
Args:
param (int): description
Returns:
bool: description
"""
pass
Doxygen and/or doxypypy does ignore this information in my case. Is this the correct behaviour or do I make something wrong?
I have written python bindings in C++ using boost::python which generates a shared object.
It looks like doxypypy wants a python source file as an input. Is there any way to give it a shared object?
Thanks!
Coroutines (functions with the prefix async), as introduced by the asyncio module, are not parsed.
Python 3.6.4 using pipenv to manage a virtual environment.
doxypypy==0.8.8.6, as installed by pipenv with pipenv install doxypypy
Failure can be reproduced without the need for Doxygen.
async
to make the function be a coroutine.doxypypy -a -c example.py
, targeting the example file.async def myfunction(arg1, arg2, kwarg='whatever.'):
"""
Does nothing more than demonstrate syntax.
This is an example of how a Pythonic human-readable docstring can
get parsed by doxypypy and marked up with Doxygen commands as a
regular input filter to Doxygen.
Args:
arg1: A positional argument.
arg2: Another positional argument.
Kwargs:
kwarg: A keyword argument.
Returns:
A string holding the result.
Raises:
ZeroDivisionError, AssertionError, & ValueError.
Examples:
>>> myfunction(2, 3)
'5 - 0, whatever.'
>>> myfunction(5, 0, 'oops.')
Traceback (most recent call last):
...
ZeroDivisionError: integer division or modulo by zero
>>> myfunction(4, 1, 'got it.')
'5 - 4, got it.'
>>> myfunction(23.5, 23, 'oh well.')
Traceback (most recent call last):
...
AssertionError
>>> myfunction(5, 50, 'too big.')
Traceback (most recent call last):
...
ValueError
"""
assert isinstance(arg1, int)
if arg2 > 23:
raise ValueError
return '{0} - {1}, {2}'.format(arg1 + arg2, arg1 / arg2, kwarg)```
I am extensively using decorators on classes, and looking for a solution to generate xml from code referencing those as well. Although the readme mentions decorators, I don't see them in the resulting documentation (either xml or html).
What did I miss?
In case of the following code:
import types
from winterboot.Autowired import Autowired
from winterboot.Service import Service
config = Autowired('config')
numericConverterService = Autowired('numericConverterService')
@Service
class PrepareDataService:
def prepareData(self, trainSet, problemSet):
result = types.SimpleNamespace()
result.max_length = self._calculateMaximumStringLength(trainSet, problemSet)
result.numberOfOutputNeurons = max(trainSet.loc[:, config().TRAINING_SET_OUTPUT_COLUMN])+1
result.trainValues = numericConverterService().createNumericArrayFromTextArray(
trainSet.loc[:, config().PROBLEM_SET_INPUT_COLUMN].values,
result.max_length)
result.trainResults = trainSet.loc[:, config().TRAINING_SET_OUTPUT_COLUMN].values
result.problemValues = numericConverterService().createNumericArrayFromTextArray(
problemSet.loc[:, config().PROBLEM_SET_INPUT_COLUMN].values,
result.max_length)
result.problemOids = problemSet.loc[:, config().PROBLEM_SET_ID_COLUMN].values
return result
def _calculateMaximumStringLength(self, trainSet, problemSet):
max_length = max([len(s) for s in trainSet.loc[:, config().TRAINING_SET_INPUT_COLUMN]])
max_length = max([max_length]+[len(s) for s in problemSet.loc[:, config().PROBLEM_SET_INPUT_COLUMN]])
return max_length
I would like to be able to
I am using your doxypypy filter (thanks for this filter) with my Doxygen documentation for my PyBooster project (here on GitHub). However, when I click "Definition at line 883", I am taken to the page containing the src, but I am not taken to the line specified. The URL does show the parameter for the line (basic_8py_source.html#l00883). The "Definition at line XXX" works with the documentation of my C code, but after using doxypypy, the "Definition at line XXX" does not work with the Python code (as it did prior to using doxypypy).
When processing following file:
class A:
def __init__(self, x, y):
"""Arguments:
x - is x
y - is obviously y
"""
pass
I get an error:
Traceback (most recent call last):
File "e:\python34(86)\lib\runpy.py", line 170, in _run_module_as_main
"__main__", mod_spec)
File "e:\python34(86)\lib\runpy.py", line 85, in _run_code
exec(code, run_globals)
File "E:\Python34(86)\Scripts\doxypypy.exe\__main__.py", line 9, in
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 874, in main
astWalker.parseLines()
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 757, in parseLines
self.visit(inAst)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 573, in visit
return visitor(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 603, in visit_Module
self.generic_visit(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 558, in generic_visit
self.visit(item, containingNodes=kwargs['containingNodes'])
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 573, in visit
return visitor(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 749, in visit_ClassDef
self.generic_visit(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 558, in generic_visit
self.visit(item, containingNodes=kwargs['containingNodes'])
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 573, in visit
return visitor(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 690, in visit_FunctionDef
containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 429, in _processDocstring
docstringConverter.send(lineInfo)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 248, in __alterDocstring
lines[-1], inCodeBlock)
IndexError: list index out of range
If Arguments
is replaced with another, non-significant, word (e.g. Lemon
), another error is raised:
Traceback (most recent call last):
File "e:\python34(86)\lib\runpy.py", line 170, in _run_module_as_main
"__main__", mod_spec)
File "e:\python34(86)\lib\runpy.py", line 85, in _run_code
exec(code, run_globals)
File "E:\Python34(86)\Scripts\doxypypy.exe\__main__.py", line 9, in
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 874, in main
astWalker.parseLines()
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 757, in parseLines
self.visit(inAst)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 573, in visit
return visitor(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 603, in visit_Module
self.generic_visit(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 558, in generic_visit
self.visit(item, containingNodes=kwargs['containingNodes'])
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 573, in visit
return visitor(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 749, in visit_ClassDef
self.generic_visit(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 558, in generic_visit
self.visit(item, containingNodes=kwargs['containingNodes'])
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 573, in visit
return visitor(node, containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 690, in visit_FunctionDef
containingNodes=containingNodes)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 429, in _processDocstring
docstringConverter.send(lineInfo)
File "e:\python34(86)\lib\site-packages\doxypypy\doxypypy.py", line 310, in __alterDocstring
if lines[-1] == '# @par':
Errors disappear if :
is removed from the first line.
The single line regular expressions match too many words. For example, the file regex, ^(\s_File:?\s_)(.*)$, matches filename, File, file, etc. Having any of these words at the beginning of a comment block for a method, for example, causes the doxypypy script to fail. A similar thing happens with date. If a method brief description starts the word "date", it is treated as a "@Date" tag rather than a string. One solution is to make these tags more explicit by making the semi-colon as not optional. Or perhaps they can only be active in the top module comment block, but not in any class/method/function/etc. definitions. I understand that these expressions are written for flexibility, but right now they are too flexible.
In Windows, non-ascii unicode characters raise
UnicodeEncodeError: 'charmap' codec can't encode characters in position 8257-8259: character maps to
Finding inspiration here: https://stackoverflow.com/a/30673656, I've replaced
print(astWalker.getLines())
with
import sys, io
default_out = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
print(astWalker.getLines()), file=default_out)
as a workaround. Not sure this is the best thing to do, but it works.
Following previous comment I did about class attributes translation into doxygen format, you have update @param inti @var.
Unfortunately the fix is not so easy....
The syntax is different and the location of the comments is different as well.
Actually you have:
class myClass:
...
But the syntax for doxygen is:
class myClass:
## @var var1
# desc1...
## @var var2
# desc2...
...
I don't know why they have choose this approach in doxygen. I prefer yours (find it more coherent) but it's not working.
When filtering multiline docstrings, the line containing the terminating sequence (""") is included in the generated code fragments from the Doxygen option INLINE_SOURCES. This results in incorrect syntax highlighting.
For example:
def f():
"""
arbitrary text
"""
do_stuff()
Will output the following code with the documentation of the function
"""
do_stuff()
In a class,
class foo: """ My awesome class """ @property def thing(self): """ Important property """ pass
is not parsed as a property of the class. It is simply shown as a public method of the class.
Output from doxypypy:
## @brief My awesome class class foo: ## @brief Important property @property def thing(self): pass
I would expect:
## @brief My awesome class class foo: ## @property thing # Important property
There is also the @thing.getter() and @thing.setter() and I'm not sure if/how that could be handled.
I'm using the Python3 version of doxypypy and have noticed strange behavior with the generation of @code
and @endcode
tags. Here are some examples.
Notice the extra @endcode
:
## @brief Transition test decorator
#
#
# @param target_s_name Name of the target state
#
# @b Examples
# @code
# @endcode
# @state('p')
# def p(self):
# '''In state p'''
# pass
# @transition('q')
# def p(self):
# '''Test for transition to q.'''
# ...
# @endcode
#
This code was generated from:
def transition(self, target_s_name):
"""
Transition test decorator
Args:
target_s_name: Name of the target state
Example:
@state('p')
def p(self):
'''In state p'''
pass
@transition('q')
def p(self):
'''Test for transition to q.'''
...
"""
Here's another example. Notice that the @endcode
is completely missing from this case, and in fact this isn't a code sample at all:
## @brief Add a new state or replace an existing one.
#
#
# @param s_name Name of the state, must be hashable.
# @param state_data Data associated with this state.
# @param activity Callable to execute when in the state. The call
# @code
# signature is activity(statemachine, current_state, state)
#
def add_state(self, s_name, state_data=None, activity=None):
record = _StateRecord(s_name, state_data, activity)
self._state_records[s_name] = record
This was generated from
def add_state(self, s_name, state_data=None, activity=None):
"""
Add a new state or replace an existing one.
Args:
s_name: Name of the state, must be hashable.
state_data: Data associated with this state.
activity: Callable to execute when in the state. The call
signature is activity(statemachine, current_state, state)
"""
I'm using today's build. I don't know when this issue was introduced because I haven't been using doxypypy since August.
If you'd like the original source, just graph the head at https://github.com/CodieCodemonkey/PyCog.
I'm currently running into an issue with module-level docstrings as
well. Using the code-snippet below, the module-level docstring
replaces the documentation for the foo function.
If I through an import between the the module-level docstring and then
the foo function, it works almost as expected. The foo function is
correctly documented but the module-level docstring does not show up
in the Doxygen results.
"""
This module does something.
Here are some interesting things about it.
"""
def foo(bar):
"""Do foo on bar.
Args:
bar: a bar object
Returns:
The result of fooing a bar.
"""
pass
Any thoughts on how to fix this?
This is because of the line chdir(dirname(file)). Since dirname(file) returns "" when in the same directory as setup.py, chdir takes "" and thus throws an exception.
Correct me if I'm wrong.
Hi,
I've recently setup a python project, for the docs I'm using
python code -> Doxygen -> (filtered via doxypypy) -> Breathe -> Sphinx Docs
This all seems to work fine, however the types of function parameters are set to the same as the name in the XML output from Doxygen
What this leads to in the eventual html output is something like
read_makefile(self self)
write_makefile(self self, contents contents)
An example here
Since Breathe doesn't know it needs to ignore the types for python you just end up with the parameter doubled up such as "contents contents"
Ideally if doxypypy had an option for leaving the type field empty for function parameters then this would solve this.
A question! I've recently tried doxypypy in conjunction with python 2.7.2 and Doxygen 1.7.6.1. I seem to be having a hard time getting module docstrings to be processed - unless I use a doxygen tag like @brief in the comment. At the function or class level things seem fine. Does any one else have similar issues?
I am using doxygen 1.8.15 to document Python scripts.
In the init method of my class I would like to document my variable this way:
## @var Array of Hashes $__vms
# This is a complex structure having this details ... (long text)
__vms = None
...
After processed by doxypypy this was the result:
## @var Array of Hashes $__vms
# This is a complex structure having this details ... (long text)
## @var __vms
# @hideinitializer
# @Private
__vms = None
...
But the output of doxypypy should be without the second ##@var line.
Is there a walk around?
I am running doxypypy on Windows 10 and ran into the following exception. This seems to happen between reading and parsing a file which doesnt contain any docstrings or doxygen comments. I can't really share anything more as I work on a confidential project. I've gone through the files listed in the stacktrace below but can't seem to figure out why this would be the case.
Traceback (most recent call last):
File "c:\python27\lib\runpy.py", line 174, in _run_module_as_main
"__main__", fname, loader, pkg_name)
File "c:\python27\lib\runpy.py", line 72, in _run_code
exec code in run_globals
File "C:\Python27\Scripts\doxypypy.exe\__main__.py", line 9, in <module>
File "c:\python27\lib\site-packages\doxypypy\doxypypy.py", line 830, in main
astWalker.parseLines()
File "c:\python27\lib\site-packages\doxypypy\doxypypy.py", line 743, in parseLines
self.visit(inAst)
File "c:\python27\lib\site-packages\doxypypy\doxypypy.py", line 569, in visit
return visitor(node, containingNodes=containingNodes)
File "c:\python27\lib\site-packages\doxypypy\doxypypy.py", line 595, in visit_Module
[]))
File "c:\python27\lib\site-packages\doxypypy\doxypypy.py", line 553, in generic_visit
self.visit(item, containingNodes=kwargs['containingNodes'])
File "c:\python27\lib\site-packages\doxypypy\doxypypy.py", line 569, in visit
return visitor(node, containingNodes=containingNodes)
File "c:\python27\lib\site-packages\doxypypy\doxypypy.py", line 610, in visit_Assign
match = AstWalker.__attributeRE.match(self.lines[lineNum])
IndexError: list index out of range
Take a look at the following block.
class Foo(object):
def method(self, bar):
"""Do something with Foo.
More about Foo method.
Arguments:
bar: Something to do something with.
"""
pass
This is converted by doxypypy to:
class Foo(object):
## @brief Do something with Foo.
#
# More about Foo method.
#
#
# @param bar Something to do something with.
#
def method(self, bar):
pass
Since most of the indentation is kept on "More about Foo method." that line is treated as a code block if MARKDOWN_SUPPORT=YES (at least in Doxygen 1.8.5). This will happen only if some part of the comment block (in this case the @param
) is indented far enough to the left that the relative difference in indentation is 4 or more spaces.
I'm not sure what exactly doxypypy should do about this, but it seems to me that if it stripped off the minimal indent (for non-blank lines), that would make it easier to avoid issues with MARKDOWN_SUPPORT=YES.
I have a
@code
key1: value1
key2: value2
@encode
And this is rended with key1 <tab> value1
. But this should not be parsed and interpreted.
Also, comments such as <!-- a commnt -->
are removed if only indented with 4 spaces (without the @code
envirnoment.
Hi,
I recently gave doxypypy a try and noticed, that See also:
sections are ignored. Doxygen has a @sa
command that will render a See also section with links to the mentioned functions. Could you please add this section to doxypypy? In my mind it should support the following syntax.
See also:
function_a
member_b
Maybe also the following.
See also:
function_a, member_b
And produce the following output, or similar.
@sa function_a
@sa member_b
It's worth mentioning, that doxygen can take some hints on automatic link generation.
What do you think about this?
Best,
Andy
This looks great, but chokes on Python 3, are you planning on a port? Thanks for doing this!
UPDATE: I ran doxypypy.py through the utility 2to3 that comes with Python3, and it seems to work just fine! I haven't done thorough testing yet, but it is reporting my undocumented entities correctly as far as I can tell.
UPDATE #2: Running 2to3 stops doxypypy from crashing, but it doesn't seem to generate the filtered code. I'll look into it if I get a chance, but can't say when that will be.
The first line of the doxypypy.py script is
#!/usr/bin/env python
This creates a dependency on whatever python version 'python' refers to. Which in turn leads to non-obvious parser crashes when using python3 code if the system python version is 2.x
Possible fix is to remove the shebang and ujpdate instructions to use 'python doxypypy.py' instead (or an explicit python3).
Other work-arounds would be a wrapper which accepts some kind of python2/python3 option, but with a developer userbase I don't think this is necessary.
For a PEP-8 compliant class method definition:
@classmethod
def sample(cls, param):
Doxygen will complain (after doxypypy filtering) that "cls" wasn't documented. This should be treated the same way that "self" is for instance methods.
I notice in sample.py that the sample classmethod definition uses "self" in place of "cls", which is a violation of PEP-8.
Hi,
I don't mean to flood you, =) but I also have an issue with raw docstrings.
I'm using doxygen's maths capabilities to document what my maths functions are doing. These are generally quite complicated TeX expressions.
TeX maths contain a lot of backslashes, e.g. \sqrt
, \frac
, \int
, etc. However, since docstrings are regular python strings, the backslash acts as an escape and can trigger unwanted behaviour. This becomes visible when you try to read the docstring in an interactive session, e.g. IPython. Suddenly, it contains non-printable characters.
My fix for this is to use raw strings as doc-strings. I.e. r"""docstring..."""
. Unfortunately, doxypypy doesn't like this very much. I've forked your repo and added a test to illustrate what I'm talking about.
I'll just link to the commits. The commit messages are descriptive:
Direct links to the files:
Do you have an idea what might cause this problem?
Or, if you have any suggestion how to circumvent this problem I'd be all ears.
Best,
Andy
This then breaks doxygen's comment parsing.
Defining linesep
as \n
works.
Hello,
I'm new to python and I've been trying to use doxygen with doxypypy.
So far, it works as I expected, but i wonder if there is a way to show the expected type of an incoming parameter or return value so that it's correctly interpreted by doxygen afterward ?
Thank you
I've been using a syntax for documenting exceptions that looks like:
Raises:
SomeException: Something bad happened.
This works correctly in that SomeException becomes a link to the exception class' documentation.
The example syntax, though, has just the exception name followed immediately by a period, which won't get linked correctly.
These python special methods are missing from my documentation now I used this project.
They are showed as with missing documentation.
I got to revert back to the standard doxygen which included then correctly.
It seems that the @fn tag to detect a function removes prior tags in that comment block. I think the @fn can just be removed per the doxygen documentation:
"This command is only needed if a comment block is not placed in front (or behind) the function declaration or definition...If your comment block is in front of the function declaration or definition this command can (and to avoid redundancy should) be omitted."
Perhaps there is a way to change the behavior, but the below example outlines the issue I see.
No @fn tag:
## @brief Documentation for a method.
# @param self the object pointer
def PyMethod(self):
pass
Putting the @fn tag above the function definition:
## @brief Documentation for a method.
# @param self the object pointer
# @fn PyMethod
def PyMethod(self):
pass
Hi,
This might be related to #42
but do we know if there's a way to handle attributes with multiple lines?
such as the below
class TestClass(object):
"""Test Class.
Attributes:
value1: This is a test.
value2: This is a 2nd test.
value3: This is a multiple line attribute
This is a second line
"""
doxypypy seems to treat any variable that beings with a single or double underscore as being a class member, and marks it with a @var
comment, even when it is merely a local variable. For example this input:
def answer():
_x = 13
__y = 31
return _x + __y
Is filtered into:
def answer():
## @var _x
# @hideinitializer
# @protected
_x = 13
## @var __y
# @hideinitializer
# @private
__y = 31
return _x + __y
This in turn results in doxygen warning that the documented symbol was "not declared or defined".
In my case, there were only a handful of such issues in our codebase, and I intend to rename the variables on the basis that local variables that start with an underscore are bad style. Nevertheless, I don't think this is was doxypypy's intended behaviour, so I am reporting it as a bug.
My project:
A/__init.py
A/mod.py: def f(): pass
B/__init__.py
B/mod.py: def f(): pass
main.py:
from B.mod import f
def main():
f()
doxygen see that main.main calls A.f()
There is a way to have a correct call graph ?
Note:
doxygen dosen't understand the 1 line syntax:
def main(): f()
There are no instructions on how to install nor use this. That will be particularly awkward for people unfamiliar with dOxygen filters.
Hi and thanks for the filter. I have started the asciidoc porting to Python 3, and I have used Doxygen to get a big picture. The script was converted with 2to3
. The syntax error is reported for the print(line, file=f)
(which is not what is normally used, in my opinion, anyway):
Generating code for file asciidoc3.py...
Traceback (most recent call last):
File "C:\Python27\lib\runpy.py", line 162, in _run_module_as_main
"__main__", fname, loader, pkg_name)
File "C:\Python27\lib\runpy.py", line 72, in _run_code
exec code in run_globals
File "C:\Python27\lib\site-packages\doxypypy-0.8.8.6-py2.7.egg\doxypypy\doxypy
py.py", line 836, in <module>
main()
File "C:\Python27\lib\site-packages\doxypypy-0.8.8.6-py2.7.egg\doxypypy\doxypy
py.py", line 830, in main
astWalker.parseLines()
File "C:\Python27\lib\site-packages\doxypypy-0.8.8.6-py2.7.egg\doxypypy\doxypy
py.py", line 741, in parseLines
inAst = parse(''.join(self.lines), self.inFilename)
File "C:\Python27\lib\ast.py", line 37, in parse
return compile(source, filename, mode, PyCF_ONLY_AST)
File "D:/Software/asciidoc/asciidoc3.py", line 6061
print(line, file=f)
^
SyntaxError: invalid syntax
The problem can be manifested at the sources from https://github.com/pepr/asciidoc/tree/py3dev, commit point a1799470619
. The last official Doxygen and graphviz were installed. When the line is replaced by f.write(line + '\n')
, the filter works fine -- see commit d64db2f9bed
.
I am working on an older project that documents classes like this:
class Version:
"""
Parse and compare AsciiDoc version numbers.
Instance attributes:
string: String version number 'major.minor[.micro][suffix]'.
major: Integer major version number.
minor: Integer minor version number.
micro: Integer micro version number.
suffix: Suffix (begins with non-numeric character) is ignored when comparing.
Examples:
>>> Version('8.2.5') < Version('8.3 beta 1')
True
>>> Version('8.3.0') == Version('8.3. beta 1')
True
etc.
"""
def __init__(self, version):
self.string = version #!< comment like this does not work
reo = re.match(r'^(\d+)\.(\d+)(\.(\d+))?\s*(.*?)\s*$', self.string)
if not reo:
raise ValueError('invalid version number: %s' % self.string)
groups = reo.groups()
self.major = int(groups[0])
self.minor = int(groups[1])
self.micro = int(groups[3] or '0')
self.suffix = groups[4] or ''
The Instance attributes:
could be replaced by Attributes:
. Then the docstring is nicely formatted, but the subtitle is misleading. Doxygen extracts "Public Attributes" from the __init__()
; however, I did not find a way how to document them. If it were possible, I would remove it from docstring. Is there any recommended way?
Also the string: String version number 'major.minor[.micro][suffix]'.
was earlier string: String version number '<major>.<minor>[.<micro>][<suffix>]'.
-- nor doxypypy nor Doxygen html escaped the angle brackets. Could this be done by doxypypy?
Actually you add the @protected
and @private
commands if the function has an single underscore _
respectively double underscore __
.
The interpretation of the underscores is correct but doxygen will ignore them if the language is object-oriented:
\protected
Indicates that the member documented by the comment block is protected, i.e., should only be accessed by other members in the same or derived classes.Note that Doxygen automatically detects the protection level of members in object-oriented languages. This command is intended for use only when the language does not support the concept of protection level natively (e.g. C, PHP 4).
(same for private)
doxygen actually mark everything as private which begins with one or more underscore.
Of course you can nothing do to change that, I want to only leave this information here for users which are confused (and that you do not have to add the @protected
and @private
commands).
I opened an issue so that it will be corrected.
I liked the human-readable docstring example and tried it with an argument called "date" when I came across an oddity
example in Python
Args:
arg1: some argument
date: another argument
arg2: yet another argument
doxypypy output
# Args:
# arg1: some argument
# date: another argument
# arg2: yet another argument
and the doygen output looks like this
Parameters
arg1 some argument
Date
Date another argument
Parameters
arg2 yet another argument
I figure something similar would happen with any parameter named like a doxygen keyword.
How about rewriting the args block in the doxypypy output to something like
# @param arg1 some argument
# @param date another argument
# @param arg2 yet another argument
def foobar(a, b, c):
""" Description
Args:
a:
b:
c: Description
"""
In that case only c
is shown as a parameter (under sub-headline ''Parameters'').
One "usecase" of API documentation for me is to see which functions/methods/classes/paramters are there but doesn't have documentation.
I got the following exception while running on doxywizard: (I truncated it to the relevant point)
Traceback (most recent call last):
...
File "/usr/local/lib/python2.7/dist-packages/doxypypy/doxypypy.py", line 470, in _processDocstring
if '@property\t' in firstVarLine:
UnboundLocalError: local variable 'firstVarLine' referenced before assignment
I found looking to your code on the repository that in line 471 yo checks over the firstVarLine variable which may have not been assigned if the previous for loop iterates 0 times.
Maybe extending that if condition with (lastVarLineNum > 0) would prevent the problem.
(Not checked the full logic, just an "on the fly" idea)
if lastVarLineNum > 0 and '@property\t' in firstVarLine:
Thatt’s not really a bug, rather a proposal.
For C/C++, Doxygen supports documentation after a member, like this:
int foo = 0; /**< More on `foo`. */
Unfortunately, it seems Doxygen does not support it for Python. This, does not work:
FOO = 0 ##< More on `FOO`.
May be there is a way to tweak Doxypypy so that it turns the above into something like this:
## More on `FOO`.
FOO = 0
That said, I don’t really know if it’s Doxygen or Doxypypy which should support it.
The solution proposed for issue #25 does not, in fact, accurately detect file format when BOM is absent.
If the 32 first characters are pure ASCII, then 'ascii' encoding is "detected". When other characters are present, an encoding compatible with that character is chosen, but it needs not be the correct one.
For instance, with character é
present in the first line, I get encoding 'cp-1252' on Windows, while other characters are present later in the file that can't be represented in that encoding (box drawing characters).
The classical coding specification -*- coding: utf-8 -*-
is not considered at all.
Updated location seems to be:
https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments
Hello,
I am using function decorators in my code, which get misinterpreted by Doxygen. For example, a SocketIO decorator with a namespace:
@socketio.on('some_event', namespace='/test')
def event_handler(data):
"""
DOCSTRING HERE
"""
is recognized as a namespace itself, and the docstring is not associated to the function.
I tried to add ad-hoc aliases to the Doxyfile so that it gets ignored by Doxygen's parser, without success. Any suggestions?
"""
Wrapper for @ref wait_until_state_reached, for cases when the intended call is for that marker to be reached
Args:
marker_extensions (dict): Extra content for the marker
marker_name (str) : Identifier of the marker.
name (str): Key of marker content. If empty string, then the content will be an empty dict
timeout (int): the max amount of seconds to wait for this marker to be reached.
error_contents (list of dict) : List of markers treated as error condition, causing the
method to return false if one was found.
Content of dict {"\<MarkerType\>": {\<Marker Content\>}}
"""
## @brief Wrapper for @ref wait_until_state_reached, for cases when the intended call is for that marker to be reached
#
#
# @param marker_extensions Extra content for the marker
#
# @param marker_name Identifier of the marker.
#
# @param name Key of marker content. If empty string, then the content will be an empty dict
#
# @param timeout the max amount of seconds to wait for this marker to be reached.
# error_contents (list of dict) : List of markers treated as error condition, causing the
# method to return false if one was found.
# Content of dict {"\<MarkerType\>": {\<Marker Content\>}}
#
witch forces doxygen to put "error_contents ....." into a code block.
we expect a @param here.
Maybe the regex "__errorLineRE" have to be fine tuned.
To document a module (as a namespace) I need to write in the file:
## @package name.of.module
#
# description
#
I would like to be able to write only docstrings and that they are directly translated (as in your examples). The best would be not to rewrite @package
but I can live with it. So basically
""" description
"""
Oh, and I'm using Python3
Using Python 3.5, and doxypypy 0.8.8.6 if I run the suggested py_filter.bat file against a python file that's in UTF-8-BOM, then doxypypy raises an exception (as below).
Even happens with a completely empty file, so I guess it's balking at the Unicode header.
ANSI files work fine.
Traceback (most recent call last):
File "C:\Python35\lib\runpy.py", line 170, in _run_module_as_main
"__main__", mod_spec)
File "C:\Python35\lib\runpy.py", line 85, in _run_code
exec(code, run_globals)
File "C:\Python35\lib\site-packages\doxypypy\doxypypy.py", line 836, in <modul
e>
main()
File "C:\Python35\lib\site-packages\doxypypy\doxypypy.py", line 830, in main
astWalker.parseLines()
File "C:\Python35\lib\site-packages\doxypypy\doxypypy.py", line 741, in parseL
ines
inAst = parse(''.join(self.lines), self.inFilename)
File "C:\Python35\lib\ast.py", line 35, in parse
return compile(source, filename, mode, PyCF_ONLY_AST)
File "c:\myscript\test.py", line 1
"""
^
SyntaxError: invalid character in identifier
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.