python-sphinx记录不带py扩展名的脚本

Question

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

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

如何让Sphinx相信它应该记录该脚本？示例错误：

/home/XXX/YYYYY/development/dst/build/index.rst:25：(警告/2) autodoc无法导入/查找模块'site_scons.random'，它报告错误：“没有命名为/home/XXX/YYYYY/development/dst/build/index.rst:25:的模块”，请检查您的拼写和sys.path

Answer 1

为了让你的脚本成为一个模块，它需要包含.py后缀。从Python docs

Python模块是包含

定义和语句的文件。文件名是模块名称，后缀为.py。

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

Answer 2

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

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

Answer 3

作为@dirn的mentioned，模块需要一个.py扩展才能被认为是这样的。

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

Python

• 在您的Sphinx根文件夹上创建一个名为links的目录(即，它将是source和build)

• On的同级目录，创建指向您的脚本的相对链接，将.py添加到它们的名称中

• 将这个新目录添加到conf.py上的Path setup：Python下的Python路径中。您可以使用类似于<代码>d17的内容将您的脚本作为一个模块读取并记录下来。<代码>H218<代码>F219

示例项目将如下所示：

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目录，因为这些文件只是实际脚本的副本。

人们可能也可以通过try to hack this through the imp module来获取它，但我认为那会更难看。我还没试过呢。