自从有了Sphinx，程序员也爱写文档了

Sphinx （https://www.sphinx-doc.org/）是一个强大的文档生成工具，最初为 Python 项目设计，但它支持多种开发语言和格式。通过扩展和插件，Sphinx 可以生成多种语言的文档，包括 Python、C/C++、Java、JavaScript、Go、Rust 等。

1. Python

Sphinx 最初为 Python 项目设计，支持自动提取 Python 代码的文档字符串（docstring）并生成文档。

代码示例

def add(a: int, b: int) -> int:
    """
    Add two numbers.

    :param a: The first number
    :param b: The second number
    :return: The sum of the two numbers
    """
    return a + b

配置

在 conf.py 中启用 autodoc 扩展：

extensions = [
    'sphinx.ext.autodoc',  # 自动提取 docstring
    'sphinx.ext.napoleon', # 支持 Google 和 NumPy 风格的 docstring
]

生成文档

在 .rst 文件中使用 autodoc 指令：

.. automodule:: mymodule
   :members:

2. C/C++

Sphinx 支持 C 和 C++ 项目，通过 sphinx.ext.intersphinx 和 breathe 扩展，可以解析 Doxygen 生成的 XML 文件。

代码示例

/**
 * Add two integers.
 *
 * @param a The first integer
 * @param b The second integer
 * @return The sum of the two integers
 */
int add(int a, int b) {
    return a + b;
}

配置

1. 安装 breathe：
2. 在 conf.py 中启用 breathe：

生成文档

在 .rst 文件中使用 breathe 指令：

.. doxygenfile:: myfile.h
   :project: MyProject

3. Java

Sphinx 支持 Java 项目，通过 sphinxcontrib-javadoc 扩展，可以解析 Javadoc。

代码示例

/**
 * A simple calculator class.
 */
public class Calculator {
    /**
     * Add two numbers.
     *
     * @param a The first number
     * @param b The second number
     * @return The sum of the two numbers
     */
    public int add(int a, int b) {
        return a + b;
    }
}

配置

1. 安装 sphinxcontrib-javadoc：
2. 在 conf.py 中启用扩展：

生成文档

在 .rst 文件中使用 javadoc 指令：

.. javadoc:: Calculator

4. JavaScript

Sphinx 支持 JavaScript 项目，通过 sphinx-js 扩展，可以解析 JSDoc 注释。

代码示例

/**
 * Add two numbers.
 *
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of the two numbers
 */
function add(a, b) {
    return a + b;
}

配置

1. 安装 sphinx-js：
2. 在 conf.py 中启用扩展：

生成文档

在 .rst 文件中使用 js 指令：

.. js:autofunction:: add

5. Go

Sphinx 支持 Go 项目，通过 sphinxcontrib-golangdomain 扩展，可以解析 Go 代码。

代码示例

// Add adds two integers and returns the result.
func Add(a int, b int) int {
    return a + b
}

配置

1. 安装 sphinxcontrib-golangdomain：
2. 在 conf.py 中启用扩展：

生成文档

在 .rst 文件中使用 go 指令：

.. go:function:: Add(a int, b int) int
   :module: mymodule

6. Rust

Sphinx 支持 Rust 项目，通过 sphinxcontrib-rustdomain 扩展，可以解析 Rust 代码。

代码示例

/// Add two integers.
///
/// # Arguments
///
/// * `a` - The first integer
/// * `b` - The second integer
///
/// # Returns
///
/// The sum of the two integers.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

配置

1. 安装 sphinxcontrib-rustdomain：
2. 在 conf.py 中启用扩展：

生成文档

在 .rst 文件中使用 rust 指令：

.. rust:function:: add(a: i32, b: i32) -> i32

7. Markdown

虽然 Sphinx 默认使用 reStructuredText（.rst），但通过 recommonmark 或 MyST 扩展，可以支持 Markdown 格式。

代码示例

Markdown 文件 example.md：

# Add Function

This function adds two numbers.

```python
def add(a, b):
    return a + b


#### **配置**
1. 安装 `myst-parser`：
   ```bash
   pip install myst-parser

1. 在 conf.py 中启用扩展：

生成文档

直接将 Markdown 文件添加到 toctree：

.. toctree::
   :maxdepth: 2

   example.md

Sphinx 支持多种开发语言和文档格式，以下是常用语言及其扩展：

• Python：sphinx.ext.autodoc
• C/C++：breathe
• Java：sphinxcontrib-javadoc
• JavaScript：sphinx-js
• Go：sphinxcontrib-golangdomain
• Rust：sphinxcontrib-rustdomain
• Markdown：myst-parser

通过合理配置和扩展，Sphinx 可以满足多语言、多格式的文档生成需求，适用于各种开发项目。