【发布时间】：2018-06-28 13:39:21
【问题描述】：
我想要的只是从我的源代码中的函数文档字符串生成API 文档，大概是通过 sphinx 的 autodoc 扩展，以包含我的精益 API 文档。我的代码遵循函数式编程范式，而不是 OOP，如下所示。
作为第二步，我可能会为项目添加一个或多个文档页面，托管介绍性 cmets、代码示例（我猜是利用 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)
或者您会为此用例推荐不同的工具和流程吗？
非常感谢！
【问题讨论】：
-
我相信它们是相关的，但不重复
-
请根据您面临的实际问题提出一个实用的、可回答的问题（请参阅stackoverflow.com/help/dont-ask）。到目前为止，您基本上只是说 Sphinx 文档“有点密集”。这不是问题陈述。
-
好的，我在问题中添加了更多内容，并在链接答案的聊天部分中将
-F添加到我的命令中，但结果仍然相同：不是获取包含在rst文件中的文档字符串。我希望整个流程不像@Dror 所怀疑的那样繁琐。 -
是的，sphinx-apidoc 生成包含
automodule指令的 RST 源文件。运行该工具后，您需要运行 sphinx-build 以生成 HTML 输出。