python - 使用 twisted 和 Sphinx 自动生成命令文档

Question

我有一个项目，我使用 buildout 生成许多 cmdline 工具，并使用 Sphinx 生成文档。

有没有一种方法可以让我在 cmdline 的代码定义附近编写文档，然后让 Sphinx 使用每个命令的代码中的文档字符串为一页中的所有命令生成文档？

Answer 1

A partial solution is to use "autofunction" (see autodoc documentation) to document your code. For example with a .rst file like this:

Command line tools
==================

.. autofunction:: mypackage.tools.do_something
.. autofunction:: mypackage.importtasks.import
.. autofunction:: mypackage.feed_the_cat

This'll document them like functions, which might not look as nice.

Another solution is to generate a proper .rst file from the docstring yourself. You can generate it into the sphinx directory and use it from there. As an example you can look at a README.rst I generated for a collection of tools (console_scripts entry points like yours, btw) and at the script that generates the README.

You basically iterate over a bunch of files and add the relevant .__doc__ items to a text file. I couldn't find how to use setuptools or pkginfo to get my hands on the console_scripts entry from the setup.py, but that's something you can do if needed in a custom script :-)