文档API生成工具

1. Python
2. C++
- 2.1. Doxygen
- 2.2. Sphinx for C++（对比Doxygen）
3. Java
- 3.1. JavaDoc
4. Golang
5. 其他
- 5.1. Pandoc
  - 5.1.1. markdown转docx

1. Python

1.1. pydoc（python自带，已废弃）

据说配色及其丑陋……

1.2. pdoc（注意，不是pydoc）

pdoc 是一个简单易用的命令行工具，可以生成 Python 的 API 文档。

1.3. Sphinx

Python有个自带的工具可以生成API项目文档——pydoc，但Python3官方文档却是由sphinx生成的。可见Sphinx已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持。

Sphinx 运行前需要安装 docutils & Jinja2 & requests 库。如果需要源码支持高亮显示，则必须安装 Pygments 库.

# pip install requests jinja2 docutils
pip install sphinx

1.3.1. 支持的注释格式

Python默认

def my_function(a, b):
    """ 函数功能说明
        xxxx
    """
    return a * b

Google Style

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """

以及

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    """

NumPy Style

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : str
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """

1.3.2. 使用示例

项目目录结构示例：

+ project
    + doc
    + src
        + demo.py
        + file1.py
        + file2.py

doc目录使用来存放API(html)文档，src目录是用来存放项目的源码。

创建doc模板

cd doc/
sphinx-quickstart [doc_dir="."]

版本的格式: 1.1.0
中文的格式: zh_CN

会在doc目录下生成

+ build/（空）
+ source/
    + conf.py
    + index.rst
+ make.bat
+ Makefile

修改配置 source/conf.py

增加扩展

extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax'
]

添加 sys.path

import os
import sys
sys.path.insert(0, os.path.abspath('../../src')) #指向src目录

自动将注释生成rst文档

sphinx-apidoc -o ./source ../src

设置目录树（修改 doc/source/modules.rst 文档内容）

Welcome to XXX's documentation!
===================================

.. toctree::
   :maxdepth: 5  ### 修改了这里
   :caption: Contents:

   modules.rst  ### 注意前面是3个空格

编译
- make clean : 可选，删除doc/build下面的所有内容
- make html : 生成html文件

2. C++

2.1. Doxygen

2.2. Sphinx for C++（对比Doxygen）

微软博客

Doxygen已经存在了几十年，是一种稳定的，功能丰富的工具，用于生成文档。但是，这并非没有问题。用Doxygen生成的文档往往在视觉上比较嘈杂，具有90年代初期的风格，并且难以清晰地表示基于模板的复杂API。其标记也有局限性。尽管他们在2012年增加了对Markdown的支持，但Markdown并不是编写技术文档的最佳工具，因为它为简化而牺牲了可扩展性，功能集大小和语义标记。

Sphinx改为使用 reStructuredText ，它具有Markdown缺少的那些重要概念作为核心理想。可以将自己的“角色”和“指令”添加到标记中，以进行特定于域的自定义。

与Doxygen相比，Sphinx生成的文档看上去也更现代，更精简，并且可以更轻松地交换不同的主题，自定义显示的信息量以及修改页面的布局。

安装环境

sudo apt install doxygen  # 安装Doxygen，用于从C++头文件提取API
# pip install sphinx_rtd_theme  # 可选，安装主题
pip install breathe  # 利用Doxygen从C++提取文档
sudo apt install cmake

创建编译文件：

CatCutifier/CMakeLists.txt

cmake_minimum_required (VERSION 3.8)
project ("CatCutifier")
add_subdirectory ("CatCutifier")

CatCutifier/CatCutifier/CMakeLists.txt

add_library (CatCutifier "CatCutifier.cpp" "CatCutifier.h")
target_include_directories (CatCutifier PUBLIC .)

头文件的格式（同Doxygen）

CatCutifier/CatCutifier/CatCutifier.h
#pragma once

/**
  A fluffy feline
*/
struct cat {
    /**
    Make this cat look super cute
    */
    void make_cute();
};

配置Doxygen
```
> mkdir docs
> cd docs
> doxygen.exe -g
```
We can get something generated quickly by finding the INPUT variable in the generated Doxyfile and pointing it at our code: INPUT = ../CatCutifier 。
执行编译和文档生成
```
> doxygen.exe
```

3. Java

3.1. JavaDoc

4. Golang

5. 其他

5.1. Pandoc

Pandoc是一个文档转换工具，支持docx、markdown、html、pdf、txt等等文件格式的互相转化，常用于转换不同的标记语言格式。

apt install pandoc

5.1.1. markdown转docx

pandoc demo-math.md -o demo-math.docx