使用Doxygen生成Python与C++ 的项目文档

sudo apt-get install doxygen doxygen-gui

# 安装 graphviz 用于生成图表
sudo apt-get install graphviz

# 安装 Python 文档生成支持
pip install doxypy

/**
 * @brief 计算两个整数的和
 * 
 * 这是一个详细的描述，可以说明函数的功能、算法等
 * 
 * @param a 第一个整数
 * @param b 第二个整数
 * @return int 两个整数的和
 */
int add(int a, int b) {
    return a + b;
}

/**
 * @class Calculator
 * @brief 简单的计算器类
 * 
 * 这个类提供了基本的数学运算功能
 */
class Calculator {
public:
    /**
     * @brief 构造函数
     * @param initialValue 初始值
     */
    Calculator(double initialValue = 0);
    
    /**
     * @brief 加法运算
     * @param value 要加的值
     * @return 计算后的结果
     */
    double add(double value);
    
    /**
     * @brief 获取当前值
     * @return 当前的计算结果
     */
    double getValue() const;
    
private:
    double currentValue; ///< 当前存储的值
};

/**
 * @namespace MathUtils
 * @brief 数学工具命名空间
 * 
 * 包含各种数学相关的辅助函数和类
 */
namespace MathUtils {

/**
 * @enum Operation
 * @brief 支持的数学操作
 */
enum class Operation {
    ADD,      ///< 加法操作
    SUBTRACT, ///< 减法操作
    MULTIPLY, ///< 乘法操作
    DIVIDE    ///< 除法操作
};

/**
 * @typedef MathCallback
 * @brief 数学操作回调函数类型
 * 
 * @param a 第一个操作数
 * @param b 第二个操作数
 * @return double 计算结果
 */
using MathCallback = std::function<double(double, double)>;

/**
 * @struct ComplexNumber
 * @brief 复数数据结构
 * 
 * 表示一个复数，包含实部和虚部
 */
struct ComplexNumber {
    double real;      ///< 实部
    double imaginary; ///< 虚部
};

} // namespace MathUtils

def add_numbers(a, b):
    """
    @brief 计算两个数的和
    
    This is a detailed description that can span multiple lines
    and provide comprehensive information about the function.
    
    @param a: 第一个数字
    @param b: 第二个数字
    @return: 两个数字的和
    @retval int: 当输入为整数时
    @retval float: 当输入为浮点数时
    
    @note 这个函数同时支持整数和浮点数运算
    @warning 不支持复数运算
    
    Example:
    @code{.py}
    result = add_numbers(3, 4)  # 返回 7
    @endcode
    """
    return a + b

class Calculator:
    """
    @class Calculator
    @brief 简单的计算器类
    
    提供基本的数学运算功能，支持链式调用
    """
    
    def __init__(self, initial_value=0):
        """
        @brief 构造函数
        @param initial_value: 初始值，默认为0
        """
        self.current_value = initial_value
    
    def add(self, value):
        """
        @brief 加法运算
        @param value: 要加的值
        @return: self 支持链式调用
        """
        self.current_value += value
        return self
    
    def get_value(self):
        """
        @brief 获取当前值
        @return: 当前的计算结果
        """
        return self.current_value

"""
@package calculator
@brief 高级计算器包

提供科学计算和统计功能的完整计算器解决方案

@details
这个包包含多个模块：
- basic_calculator: 基础运算
- scientific_calculator: 科学计算
- statistical_calculator: 统计功能

@author 开发者姓名
@version 1.0.0
@date 2023-01-01
"""

# 模块级别的变量文档
MAX_ITERATIONS = 1000  ##< 最大迭代次数限制

def initialize_calculator():
    """
    @brief 初始化计算器系统
    
    这个函数必须在调用任何计算功能之前执行
    """
    pass

doxygen -g Doxyfile

# 项目信息
PROJECT_NAME           = "MyProject"
PROJECT_BRIEF          = "A cross-language C++ and Python library"
PROJECT_LOGO           = ./logo.png
OUTPUT_DIRECTORY       = ./docs

# 输入设置
INPUT                  = .
RECURSIVE              = YES
FILE_PATTERNS          = *.h *.hpp *.cpp *.cc *.cxx *.py

# 语言设置
OPTIMIZE_OUTPUT_FOR_C  = NO
OPTIMIZE_OUTPUT_JAVA   = NO
OPTIMIZE_FOR_FORTRAN   = NO
OPTIMIZE_OUTPUT_VHDL   = NO

# Python 特定设置
PYTHON_DOCSTRING       = YES

# 输出格式
GENERATE_HTML          = YES
GENERATE_LATEX         = NO
GENERATE_XML           = YES

# 图表生成
HAVE_DOT               = YES
DOT_PATH               = /home/narada/doxygen_test/doc
DOT_TRANSPARENT        = YES
DOT_MULTI_TARGETS      = YES

/**
 * # 这是一个标题
 * 
 * 这是**加粗**的文字和*斜体*的文字
 * 
 * - 列表项1
 * - 列表项2
 * 
 * [链接文本](http://example.com)
 * 
 * @note 你也可以在 Markdown 中使用 Doxygen 命令
 */

/**
 * @brief 计算欧几里得距离
 * 
 * 公式：\f$d = \sqrt{(x_2 - x_1)^2 + (y_2 - y_1)^2}\f$
 * 
 * 或者多行公式：
 * \f[
 * E = mc^2
 * \f]
 */
double euclidean_distance(double x1, double y1, double x2, double y2);

/**
 * @defgroup MathFunctions 数学函数
 * @brief 一组数学计算函数
 * @{
 */

/** @brief 加法函数 */
double add(double a, double b);

/** @brief 减法函数 */
double subtract(double a, double b);

/** @} */ // end of MathFunctions group

/**
 * @defgroup AdvancedMath 高级数学
 * @brief 高级数学运算函数
 * @{
 */

/** @brief 矩阵乘法 */
void matrix_multiply(...);

/** @} */ // end of AdvancedMath group

/**
 * @namespace MathUtils
 * @brief 跨语言数学工具库
 * 
 * 这个库同时提供 C++ 和 Python 接口
 */
namespace MathUtils {

/**
 * @brief 向量点积计算 (C++ 实现)
 * @param vec1 第一个向量
 * @param vec2 第二个向量
 * @param size 向量大小
 * @return 点积结果
 */
double dot_product(const double* vec1, const double* vec2, int size);

} // namespace MathUtils

def dot_product(vec1, vec2):
    """
    @brief 向量点积计算 (Python 接口)
    
    这个函数调用底层的 C++ 实现以提高性能
    
    @param vec1: 第一个向量，列表或数组
    @param vec2: 第二个向量，列表或数组
    @return: 点积结果
    
    @see MathUtils::dot_product() 对应的 C++ 实现
    
    Example:
    @code{.py}
    result = dot_product([1, 2, 3], [4, 5, 6])  # 返回 32
    @endcode
    """
    # 调用 C++ 扩展的实现
    pass

# 基本生成
doxygen Doxyfile

# 使用 GUI 配置（可选）
doxywizard Doxyfile

find_package(Doxygen REQUIRED)
doxygen_add_docs(
    docs
    ${PROJECT_SOURCE_DIR}/src
    ${PROJECT_SOURCE_DIR}/include
    ${PROJECT_SOURCE_DIR}/python
    COMMENT "Generating API documentation with Doxygen"
)

from setuptools import setup
from setuptools.command.install import install
import subprocess

class CustomInstall(install):
    def run(self):
        # 生成文档
        subprocess.call(['doxygen', 'Doxyfile'])
        install.run(self)

setup(
    name='your-package',
    cmdclass={'install': CustomInstall},
    # ... 其他配置
)