Document Python code with Doxygen

When documenting Python code in Doxygen, I'll leave the memo as it fits.

For comments in docstring format in python, when you place the cursor on the function, the comment will be displayed by the editing support function of VScode.

■ docstring format comment example

def leftCosets(self, H: FiniteGroup) -> Set[Set[GroupElement]]:
	"""
	@brief Calculates left cosets of H in self.

	@details foo

	:param H: subGroup of self
	:return:

	@note bar
	"""

	cosets = {frozenset(copy.deepcopy(H.elements)),}
	remain = self.elements - H.elements

	while len(remain) > 0:
		#~ Omitted ~

	return cosets

It is convenient because you can check it in the comment without moving to the function definition position just by hovering the cursor over the function.

However, the docstring format doesn't look good when documented in Doxygen because "no special commands in doxygen are supported". --I have documented a Python project in Doxygen, but the parameters are not listed properly.

So we use a filter that converts the docstring format to the doxygen format.

■ Filter to convert docstring format to Doxygen format doxyfilter_python(GitHub)

This filter converts the docstring format to doxygen format and passes it to Doxygen.

■ Doxygen format comment example

	##
	#@brief Calculates left cosets of H in self.
	#@details foo
	#
	#@param H (FiniteGroup) subGroup of self
	#@return (Set[Set[GroupElement]])
	#
	#@note bar
	def leftCosets(self, H: FiniteGroup) -> Set[Set[GroupElement]]:
	cosets = {frozenset(copy.deepcopy(H.elements)),}
	remain = self.elements - H.elements

	while len(remain) > 0:
		#~ Omitted ~

	return cosets

• Caution * If you use this as it is in a Windows environment, it will work with cp932 and Japanese characters will be garbled. When using in Windows environment, edit doxyfilter_python.py and specify the encoding "utf-8".

python：doxyfilter_python.py

import io

#~ Omitted ~ perform_Add the following line at the beginning of the fh function
        sys.stdout = io.TextIOWrapper(sys.stdout.buffer,encoding='utf-8')


#~ Omitted ~ Specify the encoding in the file open part of the main function.
        with open(file, 'r',encoding='utf-8') as fh:

■ Precautions such as Doxygen settings

Python looks more like Java than C or C ++, so set OPTMIZE_OUTPUT_JAVA to YES in the configuration file.

From "Comment blocks in Python"

-Be sure to leave one line between @brief and @details. Otherwise, the VS Code tooltip will display the items as a single line without line breaks. -Be sure to include a file comment. Otherwise the global method will not be documented.

From "Using Doxygen with Python3 with VS Code Editing Assistance"

--Expert tab-> Topics-> Input-> Specify doxyfilter_python.py with full path in INPUT_FILTER.

For the site I referred to ("Use Doxygen with Python3 while taking advantage of VS Code editing support")

Be sure to specify doxyfilter_python.py with the full path and explicitly state that it will run in python3 (otherwise it failed).

Although it is written, it seems that it is not necessary to specify python3 in an environment where only python3.x series is included.