抱歉 - 这是一个非常基础的问题:
我有几个没有 .py 扩展名的 Python 脚本。
我该如何让 Sphinx 知道它应该文档化这些脚本?例如错误提示:
/home/XXX/YYYYY/development/dst/build/index.rst:25: (WARNING/2) autodoc 无法导入/找到模块 'site_scons.random',它报告了错误:"No module named random",请检查拼写和 sys.path。
抱歉 - 这是一个非常基础的问题:
我有几个没有 .py 扩展名的 Python 脚本。
我该如何让 Sphinx 知道它应该文档化这些脚本?例如错误提示:
/home/XXX/YYYYY/development/dst/build/index.rst:25: (WARNING/2) autodoc 无法导入/找到模块 'site_scons.random',它报告了错误:"No module named random",请检查拼写和 sys.path。
.py
后缀。根据Python文档所述:.py
后缀。”automodule
导入它以生成文档。请注意保留HTML标签。正如@dirn所提到的,模块需要一个.py
扩展名才能被视为模块。
我认为更清晰的替代方案是:
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
模块尝试破解此问题,但我认为那样会更丑陋。我还没有尝试过。如果您不想让脚本以.py
文件扩展名结束,您也可以尝试以下方法。
您可以将原始脚本编写到一个.py
文件中,并创建另一个可执行文件(bash脚本)文件,该文件只是执行您的.py
文件。这样,您可以使用sphinx记录脚本(.py
)文件,并通过其他可执行文件执行它。