带有狮身人面像的文档PyCharm项目的问题

Question

我想为我的pycharm项目制作文档。我在项目目录（“模型”）中创建了一个目录docs。我安装了sphinx，并使用sphinx-quickstart制作了所有必需的文件。然后我编辑了“ conf.py”。我没有评论：

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

我添加：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinx.ext.napoleon'
]

在项目“模型”中，我有4个文件（file1.py，file2.py，file3.py和file4.py），所以我这样编辑了index.rst：

File1
=====================================

.. toctree:: model.file1
   :maxdepth: 2
   :caption: Contents:


File2
=====================================

.. toctree:: model.file2
   :maxdepth: 2
   :caption: Contents:


File3
=====================================

.. toctree:: model.file3
   :maxdepth: 2
   :caption: Contents:


File4
=====================================

.. toctree:: model.file4
   :maxdepth: 2
   :caption: Contents:

但是“ make html”之后，它给了我error: WARNING: toctree contains reference to nonexisting document 'model.file1'

您知道如何制作该文档吗？如何使用它制作pdf文件？

Answer 1

toctree directive does not do what you think it does。具体来说，它应该是一个reStructuredText文件，而不是Python文件。

相反，如果要在Python软件包及其模块中记录文档字符串，则应阅读toctree，并确保autodoc and sphinx-apidoc中有一个autodoc，以便它是一个Python软件包。

最后，将reStructuredText文件放置在包中是非常不寻常的，最佳做法是仅将代码放入包中，然后将文档内容放入其中。