Documenting UTF-8 Python code with Doxygen

Question

The following code is not parsed correctly by doxygen, the "Module Docstring" is not shown in the resulting documentation:

# -*- coding: utf-8 -*-
"""
Module Docstring
"""

If I delete the first line, it's parsed correctly. But I NEED to set up the encoding, as I use non-ASCII characters on my code. Did anyone have the same problem? I tried using doxypy, but it fails as well. Also tried many different changes in the config file.

So far, the best shot was to use the INPUT_FILTER parameter to some sort of script that strips that first line, maybe using "tail -n +3" as a filter. The problem resides that not every file needs that "coding: utf-8", so placing it in every file will be a pain. Any better ideas? Am I overlooking something?

Can you put the actual error message that you get in the question? As the documentation pointed to by Raymond Hettinger shows, UTF-8 is the default encoding for doxygen. — Roland Smith
– Roland Smith, Commented Apr 1, 2013 at 16:23
@RolandSmith I don't get any errors, just that the "Module Docstring" is not shown in the documentation generated. — Pedro Walter
– Pedro Walter, Commented Apr 1, 2013 at 16:30
It seems you have to add a special string to the module docstring. See answer below. — Roland Smith
– Roland Smith, Commented Apr 1, 2013 at 16:48

albert · Accepted Answer · 2018-12-24 16:49:05Z

1

You can specify the input encoding configuration variable:

http://www.doxygen.nl/manual/config.html#cfg_input_encoding

The variable should be set to UTF-8 (all caps, hyphen required, no spaces) as specified at http://www.gnu.org/software/libiconv/

Hope this helps. Happy documenting :-)

edited Dec 24, 2018 at 16:49

albert

9,2003 gold badges24 silver badges42 bronze badges

answered Apr 1, 2013 at 16:18

Raymond Hettinger

229k67 gold badges405 silver badges504 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

albert · Accepted Answer · 2019-03-24 16:53:58Z

0

Looking at this link, it seems you have to put @package <packagename> in the module docstring for doxygen to do something with it.

And below on the same page you can see that doxygen actually prefers you use comments instead of docstring, because doxygen special commands are not supported in docstrings.

Edit:

To avoid confusing doxygen, put the @package comment on a separate line from the coding comment.

To get doxygen to put a package "in its proper location", you should have a look at grouping, especially modules.

edited Mar 24, 2019 at 16:53

albert

9,2003 gold badges24 silver badges42 bronze badges

answered Apr 1, 2013 at 16:46

Roland Smith

43.8k3 gold badges69 silver badges98 bronze badges

4 Comments

Pedro Walter Over a year ago

Yup, I tried using @package <packagename>, but all the packages created were inserted in the same level of the root package, and I have quite a big structure here. And I tried Sphinx, but the configuration was quite hard at the beggining, doxygen had a really easy setup. But the easy is now becoming hard :)

Pedro Walter Over a year ago

I tried using the comments like described, but as the first line is also a comment, the rest of the block is ignored by the parser. Here's an example: # -- coding: utf-8 -- ## Module Docstring # Continuation of docstring

Roland Smith Over a year ago

Try putting a blank line (or a docstring) between the comments.

Pedro Walter Over a year ago

This worked partially, with the problem of creating a package in the root instead of in it's proper location: # -*- coding: utf-8 -*- <blank line> ## @package <modulename> # Module Docstring

DomTomCat · Accepted Answer · 2022-11-14 12:25:49Z

0

I faintly remember the solution being the swap in position of coding and docstring:

#!/usr/bin/env python3
"""
Module Docstring
"""
# -*- coding: utf-8 -*-

I cannot test this right now

answered Nov 14, 2022 at 12:25

DomTomCat

8,6291 gold badge54 silver badges66 bronze badges

1 Comment

albert Over a year ago

Actually this is a more general problem as addressed in github.com/doxygen/doxygen/issues/9672and fixed in github.com/doxygen/doxygen/pull/9673

Collectives™ on Stack Overflow

Documenting UTF-8 Python code with Doxygen

3 Answers 3

Comments

4 Comments

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

Comments

4 Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related