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

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?

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.

Bug

Coroutines (functions with the prefix async), as introduced by the asyncio module, are not parsed.

Test Version

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.

Reproduction

• Modify the example code by prefixing async to make the function be a coroutine.
• Run doxypypy -a -c example.py, targeting the example file.
• Code is perfectly valid python 3.5+ code, but is not parsed.
• Cry that you cannot use this cool piece of software.

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

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.

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

• https://hecatron.github.io/py-makefile-dbparse/Classes/MakeLauncher.html

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.

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?

Using the example given in the README, the examples isn't generated in its own section but instead nested in the exceptions section.

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.

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.

We have following docstring:

"""
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\>}}
    """

the processing results in:

## @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.

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

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.

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.

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

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.

• Example NumPy Style Python Docstrings
• Example Google Style Python Docstrings

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

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.

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.

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

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?

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

• find the @service annotation in relation of the class name
• for both the module-level variables I would like to find them, and preferably see the parameters for Autowired
• see the list of imports

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.

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.

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.

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

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?

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.

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?

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.

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.

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

• raw-docstring - wrong output: 79a5bca
• added to test-suite: 3f74c87
• normal docstring - right output: f3b27f9
• raw-docstring - right output (how it should be): 6c869f9

Direct links to the files:

• This is what the source shuold look like.
• This is what the doxypypy output should look like.

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

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.

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:

@brief desc.....

@var var1 desc1...

@var var2 desc2...

class myClass:
...

But the syntax for doxygen is:

@brief desc.....

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

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.

There are no instructions on how to install nor use this. That will be particularly awkward for people unfamiliar with dOxygen filters.

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!

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?

See: https://stackoverflow.com/questions/21636213/why-you-shouldnt-use-os-linesep-when-editing-on-text-mode

This then breaks doxygen's comment parsing.

Defining linesep as \n works.

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'

Updated location seems to be:

https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments

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

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

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.

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

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:

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