PyCharm项目Sphinx文档生成报错及PDF制作求助

一、修复「toctree contains reference to nonexisting document」警告 #

你遇到的这个问题很常见——你直接在toctree里写了模块路径model.file1，但Sphinx并没有对应的RST文件来生成该模块的文档内容。autodoc扩展确实能提取代码注释生成文档，但前提是得先有一个RST骨架文件帮它指定要处理哪个模块。

按以下步骤操作：

1. 切换到你的项目根目录（就是放着file1.py、file2.py和docs文件夹的model目录）。
2. 运行sphinx-apidoc命令，让它自动为你的Python文件生成RST骨架：

   sphinx-apidoc -o docs/source/ .
   

   解释下参数：-o docs/source/指定生成的RST文件要放到docs/source目录里，最后的.表示扫描当前目录下的所有Python模块。
3. 修改docs/source/index.rst，把原来分散的模块toctree换成引用生成的RST文件。比如生成的文件是file1.rst、file2.rst等，你可以把index.rst改成这样：

   Model Project Documentation
   ===========================
   
   .. toctree::
       :maxdepth: 2
       :caption: Modules Documentation:
   
       file1
       file2
       file3
       file4
   

4. 回到docs目录，重新执行make html，这个警告就应该消失了，HTML文档也能正常生成。

二、生成PDF文档 #

要生成PDF，Sphinx需要依赖TeX环境来处理LaTeX输出，步骤如下：

1. 安装TeX环境：
   • Linux/macOS用户：安装TeX Live（通过系统包管理器或者官方镜像）
   • Windows用户：安装MiKTeX（安装时记得勾选「自动下载缺失的包」选项，避免后续编译报错）
2. 回到docs目录，执行对应系统的命令：

   # Linux/macOS
   make latexpdf
   
   # Windows
   make.bat latexpdf
   

3. 编译完成后，PDF文件会存放在docs/build/latex目录下，文件名和你在sphinx-quickstart时设置的项目名称一致（比如model.pdf）。

额外小提示 #

• 因为你已经启用了sphinx.ext.napoleon，建议你的Python文件使用Google风格或NumPy风格的docstring，这样生成的文档格式会更规范美观。
• 如果后续代码更新了，重新运行sphinx-apidoc时可以加上-f参数强制覆盖旧的RST文件：sphinx-apidoc -f -o docs/source/ .

内容的提问来源于stack exchange，提问作者user11979210