flatdoc 0.1.0

安装

您可以使用pip安装flatdoc

pip install flatdoc

编写文档

您可以使用您喜欢的任何格式来编写模块、函数、类和方法文档。Markdown和reStructuredText都是很好的格式，因为它们易于输入，可读性强，并且有必要的工具来生成HTML、PDF、Postscript等。

从所有这些文档字符串构建平面文档的关键是使用!INCLUDE指令。以下是一个例子，考虑以下模块foo.py，其中包含Markdown文档字符串

"""# Foo

This module does foo.

!INCLUDE Bar, func
"""
class Bar:
    """## Bar

    This class does bar.

    !INCLUDE baz
    """
    def baz(self):
        """### baz()

        This method does baz.
        """
        pass

def func():
    """## func()

    This function does func.
    """
    pass
"""

上述模块的生成文档将是一个综合的Markdown文件

# Foo

This module does foo.

## Bar

This class does bar.

### baz()

This method does baz.

## func()

This function does func.

!INCLUDE指令

如前一小节中的示例所示，以!INCLUDE开始的文档行被视为对其他文档字符串的引用。通过此机制，可以将多个文档字符串合并到单个输出文档中。

!INCLUDE给出的参数是其他文档字符串引用的逗号分隔列表。这些引用始终相对于当前文档字符串，例如，在模块文档字符串中，可以引用任何顶级函数或类，在类中，也可以直接通过其名称引用所有方法。

当需要引用非直接子级的文档字符串时，可以使用标准的点表示法。以下一小节的例子，考虑以下情况

• 包含模块foo中类Bar的方法baz

  !INCLUDE Bar.baz

• 包含来自函数 func 的类 Bar

  !INCLUDE .Bar

• 包含一个与 foo 同级的模块 mod，来自方法 baz

  !INCLUDE ...mod

命令行用法

flatdoc 工具可用于从命令行生成文档。该命令唯一的参数是用于生成文档的顶层对象的导入名称。

您正在阅读的文档是用以下命令生成的

flatdoc flatdoc > README.rst

API 参考

flatdoc(name)

从文档字符串生成文档。

from flatdoc import flatdoc
print(flatdoc('my_pkg'))