如何从文档字符串生成API文档以获得功能代码

Question

我只想通过sphinx的autodoc扩展名从源代码中的函数文档字符串中生成 API文档，以构成我的精益API文档。我的代码遵循函数式编程范例，而不是OOP，如下所示。

第二步，我可能会为该项目添加一个或多个文档页面，托管诸如介绍性注释，代码示例（我猜是doctest）之类的内容，当然还要链接到API文档本身

从这里的文档字符串完成文档的直接流程是什么？ Sphinx是一个很好的流行工具，但是我发现它的getting started页面有点密集。

我在源目录中尝试过的操作：

$ mkdir documentation
$ sphinx-apidoc -f --ext-autodoc -o documentation .

没有错误消息，但这无法在我的源文件中找到（或处理）文档字符串；它只是为每个源创建一个rst文件，其内容如下：

tokenizer module
================

.. automodule:: tokenizer
    :members:
    :undoc-members:
    :show-inheritance:

基本上，我的源文件如下所示，其中没有太多模块仪式或面向对象的内容（我喜欢函数式编程，尽管这次是python）。我当然将下面的示例源文件截断了，它包含下面未显示的更多功能。

tokenizer.py

from hltk.util import clean, safe_get, safe_same_char

"""
    Basic tokenization for text

    not supported:

    + forms of pseuod elipsis (...)

    support for the above should be added only as part of an automata rewrite
"""

always_swallow_separators = u" \t\n\v\f\r\u200e"
always_separators = ",!?()[]{}:;"

def is_one_of(char, chars):
    '''
    Returns whether the input `char` is any of the characters of the string `chars`
    '''
    return chars.count(char)

或者您会为此用例推荐其他工具和流程吗？

非常感谢！

Answer 1

如果您发现Sphinx太笨拙且不适合用于简单项目，请尝试pdoc：

$ pdoc --html --html-dir=documentation tokenizer.py