在Pycharm中获取Sphinx，以便在生成的html中包含我的docstring

Question

我有一个Pycharm项目运行3.7.2 Python解释器，我配置了Sphinx来生成文档。我的项目有以下结构：

/my_project/
  /docs/
  /src/
    /modules/
    /tools/

在模块和工具中都有python模块，这些模块已经用docstring记录下来了。我已经将狮身人面像配置成在/docs中生成文档，但是这个文档只有一个基本的index.rst。如何从我的docstring中获取python模块文档以填充到/docs文件夹中？

Answer 1

也许你可以尝试以下几种方法：

1. 确保您要文档化的模块有一个__init__.py文件，以便以后可以适当地导入它们。在您的示例中，您的tools和modules目录需要__init__.py文件。
2. 确保您正在记录的所有模块都设置了适当的sphinx注释：

module_1.py:

"""
.. module:: module_1
   :platform: Unix, Windows
   :synopsis: A useful module indeed.
"""

def public_fn_with_sphinxy_docstring(name, state=None):
    """This function does something.

    :param name: The name to use.
    :type name: str.
    :param state: Current state to be in.
    :type state: bool.
    :returns:  int -- the return code.
    :raises: AttributeError, KeyError

    """
    return 0

1. 创建一个新的.rst文件，可能称为code.rst，其中包括您希望记录的模块。然后在您的.rst中引用这个新的index.rst文件

code.rst:

Documentation for the Code
**************************

.. automodule:: an_example_pypi_project


module #1 -- auto members
=========================

This is something I want to say that is not in the docstring.

.. automodule:: an_example_pypi_project.module_1
   :members:

index.rst:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   # other rst files you're including in your sphinx docs

   code.rst

这是一个非常好的解释和教程，如果您想要检查这一点以及。希望这能帮上忙！