doxygen chokes on init.py files

Question

I'm attempting to document a python module with Doxygen - however it seems that the existence of the __init__.py files is causing problems

Currently the __init__.py files are empty (I have tried added comments inside it like

## Nothing here

but with no success). Module namespaces are not resolved on the Doxygen side - If the following was my file:

## @package stuff
#  @author me
#  Description
#
#  Some more description

## A class that does whatever
class whatever:
    ## A method that does stuff
    def dostuff(self):
        pass

It will only pick up the 'Description' and 'Some more description' strings. Even if any of the classes in the file don't contain __init__ methods (thought there might have been naming conflicts) doxygen will not pick up the anything in the module.

I've tried using various 'EXCLUDE' directives in Doxyfile but nothing has worked.

Has anyone run into this issue before? On removing the __init__.py files everything works fine - however this is a much less than optimal solution.

Doxygen isn't the best tool for Python documentation. Consider using Sphinx (or any other Python-centric documentation generator, really; avoid ones that don't use docstrings) instead. — Cat Plus Plus
yeah I've considered using Sphinx - I guess I'll have to learn that too. I was hoping Doxygen could pump out some quick class docs... but I guess that was too easy. What I'm seeing now actually looks like it may be a bug. — Marm0t

ghammond ghammond · Accepted Answer · 2011-07-13T10:45:48

I have had exactly the same problem, I found the issue was with the naming of the package. The name given needs to be fully qualified. Otherwise you are creating documentation for a new package, in this case with the name stuff, but your class will be in an undocumented package, which unless you have EXTRACT_ALL set to yes will be hidden.

So assuming your file is called stuff.py and is in a directory called mypackage along with __init__.py then stuff.py should look something like this:

## @package mypackage.stuff
#  Description
#
#  Some more description
#  @author me

## A class that does whatever
class whatever:
    ## A method that does stuff
    def dostuff(self):
        pass

## A function that does whatever
def whatever:
    pass

doxygen chokes on __init__.py files

1 Answers

doxygen chokes on init.py files