没有 py 扩展名的 python-sphinx 记录脚本

Question

道歉 - 这是一个完整的 n00b 问题：

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

我如何说服 Sphinx 它应该记录该脚本？ 示例错误：

/home/XXX/YYYYY/development/dst/build/index.rst:25: (WARNING/2) autodoc can't import/find module 'site_scons.random'，它报告错误：“No module named random”，请检查您的拼写和 sys.path

Answer 1

为了使您的脚本成为模块，它需要包含.py后缀。 从Python文档 ：

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

如果不给它后缀，Sphinx将无法导入它以使用automodule生成文档。

Answer 2

如果您不希望脚本以.py文件扩展名结尾，您还可以尝试以下操作。

您可以将原始脚本写入.py文件并创建另一个仅执行.py文件的可执行（bash 脚本）文件。 这样，您可以使用 sphinx 记录脚本（ .py ）文件，并仍然通过其他可执行文件执行它。

Answer 3

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

我认为更干净的替代解决方案，尽管它需要更多的工作：

• 在 Sphinx 根文件夹上创建一个名为links目录（也就是说，它将是source和build的同级目录）
• 在该目录中，创建指向脚本的相对链接，在其名称中添加.py
• 将此新目录添加到conf.py上的 Python PATH Path setup ： 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

我认为这种方法的优点是您不会用.py文件污染您的bin目录，这些文件只是实际脚本的副本。

人们可能也可以尝试通过imp模块破解它以获取它，但我认为那会更丑陋。 我没试过。