Question

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

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

在模块和工具中都有python模块，这些模块已使用docstrings进行了说明。我已经将Sphinx配置为在/ docs中生成文档，但是该文档仅具有基本的index.rst。如何从我的文档字符串中获取python模块文档以填充到/ docs文件夹中？

Answer 1

也许您可以尝试以下方法：

确保要尝试记录的模块具有一个__init__.py文件，以便以后可以适当地导入它们。您的tools和modules目录需要__init__.py个文件。
确保您要记录的所有模块均已设置了正确的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

创建一个新的.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

这是一个非常不错的解释，如果您也想检查一下，请tutorial。希望有帮助！

在Pycharm中获取Sphinx，以将我的文档字符串包含在生成的html中

1 个答案: