Doxygen (python) ignores module docstrings

Question

I generate the documentation of my Python code from the docstrings via Doxygen (1.9.1) in addition with doxypypy (git version from today).

My problem is that the docstrings of a do not appear in the generated HTML. This is an example

# -*- coding: utf-8 -*-
"""This is mypackage.a
"""
import mypackage


def bar(bar):
    """
    This is the function named bar.

    The function calls `mypackage.foo()` and returns an 'a'.

    Paramters:
        bar (str): Just a parameter.

    Returns:
        str: Just an 'a'.
    """
    mypackage.foo(bar)
    return('a')

The function bar() is well documented in Doxygen HTML ouptut. But the String This is mypackage.a from the second line of that py-file do not appear anywhere.

The Doxyfile is quite big so I just show you a selection of the options I use.

BRIEF_MEMBER_DESC      = YES
REPEAT_BRIEF           = YES
ALWAYS_DETAILED_SEC    = NO
FULL_PATH_NAMES        = YES
JAVADOC_AUTOBRIEF      = NO
PYTHON_DOCSTRING       = YES
OPTIMIZE_OUTPUT_FOR_C  = NO
OPTIMIZE_OUTPUT_JAVA   = YES
OPTIMIZE_FOR_FORTRAN   = NO
OPTIMIZE_OUTPUT_VHDL   = NO
OPTIMIZE_OUTPUT_SLICE  = NO
MARKDOWN_SUPPORT       = YES
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_PACKAGE        = YES
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_CLASSES  = YES
EXTRACT_LOCAL_METHODS  = YES
EXTRACT_ANON_NSPACES   = NO
RESOLVE_UNNAMED_PARAMS = YES
HIDE_UNDOC_MEMBERS     = NO
HIDE_UNDOC_CLASSES     = NO
HIDE_FRIEND_COMPOUNDS  = NO
HIDE_IN_BODY_DOCS      = NO
INPUT                  = ../src/mypackage
FILE_PATTERNS          =
RECURSIVE              = YES
FILTER_PATTERNS        = *.py=./py_filter
GENERATE_HTML          = YES

The FILTER_PATTERNS is used because of doxypypy. But the problem also occurs if I do not use this filter. So I would assume this problem is not related to doxypypy.

Maybe this is the right answer? https://stackoverflow.com/a/58701/4865723 But I am wondering why I need extra commands like `@package`. Shouldn't it be obvious that the first docstring in a py file is the module/package documentation? — buhtz, Mar 07 '22 at 11:14
Looks like related to https://github.com/doxygen/doxygen/issues/9188 — albert, Mar 07 '22 at 11:23
Even if I remove the first line `# -*- coding: utf-8 -*-` the module docstring do not appear. — buhtz, Mar 07 '22 at 12:54
When I remove the `#` line I see the line "This is mypackage.a` in the file namespaceaa.html (my file is called aa.py). (I had, in this case, to remove the `INPUT` and `FILTER_PATTERNS ` as they are not applicable in the small test case). A number of remarks: "he Doxyfile is quite big so I just show you a selection of the options I use." why not use `doxygen -x` showing the differences between the used file and the default settings. Also read about the `PYTHON_DOCSTRING` settings (not relevant for the showing but for the layout, I would prefere `NO`). — albert, Mar 07 '22 at 13:37
Thanks a lot for your tips. I can reproduce the [Bug](https://github.com/doxygen/doxygen/issues/9188) with the current upstream version of Doxygen, without `doxypypy` involved. Is this an answer or should we just close that question? — buhtz, Mar 07 '22 at 15:33

score 1 · Accepted Answer · answered Jan 03 '23 at 23:05

A bit late. Try the following docstring. It just needs the ! after the quotes to get picked up by doxygen. Use @param and @return to get the parameter and return value highlights in the generated document.

def bar(bar):
    """!
    This is the function named bar.

    The function calls `mypackage.foo()` and returns an 'a'.

    @param bar (str): Just a parameter

    @return str: just an 'a'

    str: Just an 'a'.
    """
    mypackage.foo(bar)
    return('a')

You should also the setting `PYTHON_DOCSTRING = NO`, see documentation and my comment with the question. — albert, Jan 04 '23 at 08:44

Doxygen (python) ignores module docstrings

1 Answers1