在 Python 中，有几种常用的文档生成工具可供使用，这些工具可以使用特定的标记语法在代码中写入注释，然后生成 HTML 或其他格式的文档。

常用的文档生成工具包括：

• Sphinx: 一个功能强大的文档生成工具，支持多种输出格式，包括 HTML、LaTeX 和 PDF。Sphinx 还可以从其他文档格式（如 reStructuredText 和 Markdown）生成文档。
• pydoc: Python 自带的文档生成工具。pydoc 可以生成纯文本或 HTML 格式的文档，并且可以通过网络共享文档。
• Pycco: 一个简单的文档生成工具，可以生成 HTML 格式的文档。Pycco 使用类似于 Markdown 的语法在代码中写入注释。

要使用这些工具生成文档，你需要在代码中使用特定的标记语法写入注释。例如，在 Sphinx 中，你可以使用 .. code-block:: python 和 .. toctree:: 等指令在代码中写入注释。具体的标记语法取决于你使用的文档生成工具。

在生成文档时，除了使用注释之外，还可以使用 docstrings 来向文档中添加更多信息。docstrings 是 Python 中的特殊类型的注释，它们位于模块、类、函数或方法的第一个语句中，并使用三个双引号（”””）括起来。docstrings 可以包含对代码的描述、使用说明和其他信息，并可以被文档生成工具使用。

下面是一个使用 docstrings 的例子：

def add(x, y):
    """
    Add two numbers together and return the result.
    
    :param x: The first number to add.
    :param y: The second number to add.
    :return: The sum of x and y.
    """
    return x + y

在这个例子中，docstring 中的文本会被文档生成工具用来描述函数的用途和参数。

文档生成工具还可以自动提取代码中的类型注释，并将它们添加到文档中。例如，你可以使用 :type 标记在函数参数和返回值的注释中指定类型，文档生成工具会将这些信息添加到文档中。

def add(x: int, y: int) -> int:
    """
    Add two numbers together and return the result.
    
    :param x: The first number to add (int).
    :param y: The second number to add (int).
    :return: The sum of x and y (int).
    """
    return x + y

使用文档生成工具生成文档时，还可以使用各种其他标记来控制文档的外观和布局。

可以使用标题、列表和代码块等标记来组织文档的内容，并使用注释、缩进和其他格式化技巧来控制文档的外观。

一些文档生成工具还提供了更多的功能，例如可以从代码中提取变量、函数和类的定义，并将它们添加到文档中。这些工具还可以自动生成函数的调用示例，并将它们添加到文档中。

在使用文档生成工具生成文档时，最好养成良好的注释习惯，因为这会使文档更加易读和易用。最好在代码中写入足够的注释来描述代码的用途和工作原理，并使用 docstrings 来提供更多的使用说明和信息。

总之，文档生成工具是一种很好的方法来为 Python 代码生成文档，它们可以自动提取代码中的注释和 docstrings，并将它们转换为可读的文档。使用文档生成工具可以节省大量时间，并使代码更加易于阅读和使用。