使用Python-Sphinx文档化没有.py扩展名的脚本。

Question

抱歉 - 这是一个非常基础的问题:

我有几个没有 .py 扩展名的 Python 脚本。

我该如何让 Sphinx 知道它应该文档化这些脚本？例如错误提示：

/home/XXX/YYYYY/development/dst/build/index.rst:25: (WARNING/2) autodoc 无法导入/找到模块 'site_scons.random'，它报告了错误："No module named random"，请检查拼写和 sys.path。

- user2573436

Answer 1

为了使你的脚本成为一个模块，它需要包含.py后缀。根据Python文档所述：

“模块是包含Python定义和语句的文件。文件名是模块名称加上附加的.py后缀。”

如果不给它添加后缀，Sphinx将无法使用automodule导入它以生成文档。请注意保留HTML标签。

- dirn

---

欢呼！Sphinx是一个模块文档化包。这让我感到惊讶，因为一定有很多需要文档化的脚本。回到起点重新规划。 - user2573436

你可以使用它来编写自己的文档。但是，如果不是模块，就不能使用“automodule”。 - dirn

http://www.sphinx-doc.org/en/stable/ext/autodoc.html 上的文档说：“如果您要记录脚本（而不是库模块），请确保它们的主程序受到 if name == 'main' 条件的保护。” 这让我对记录脚本有了希望。 - krumpelstiltskin

Answer 2

正如@dirn所提到的，模块需要一个.py扩展名才能被视为模块。

我认为更清晰的替代方案是：

• 在Sphinx根目录下创建一个名为links的目录（即与source和build同级）
• 在该目录下，创建指向脚本的相对链接，并将.py添加到它们的名称中
• 在conf.py中的Path setup下，将这个新目录添加到Python PATH中：sys.path.insert(0, os.path.abspath('../links'))
• 现在，您可以使用类似于.. automodule:: my_command的命令来读取您的脚本并进行文档化。

一个示例项目如下：

proj_root/
proj_root/doc              # Sphinx root
proj_root/doc/build
proj_root/doc/links        # Remember to version this
proj_root/doc/links/my_command.py -> ../../bin/my_command
proj_root/doc/source
proj_root/doc/source/conf.py
proj_root/bin
proj_root/bin/my_command   # Actual code

我认为这种方法的优点在于，您不会在bin目录中添加与实际脚本重复的.py文件，从而污染该目录。

可能也可以通过imp模块尝试破解此问题，但我认为那样会更丑陋。我还没有尝试过。

- caxcaxcoatl

Answer 3

如果您不想让脚本以.py文件扩展名结束，您也可以尝试以下方法。

您可以将原始脚本编写到一个.py文件中，并创建另一个可执行文件（bash脚本）文件，该文件只是执行您的.py文件。这样，您可以使用sphinx记录脚本（.py）文件，并通过其他可执行文件执行它。

- fgoudra