时间戳

首页 > 解决方案 > 在 Pycharm 中获取 Sphinx 以在生成的 html 中包含我的文档字符串

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

问题描述

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

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

模块和工具中都有 python 模块，这些模块和工具都用文档字符串记录。我已将 Sphinx 配置为在 /docs 中生成文档，但此文档只有一个基本的 index.rst。如何从我的文档字符串中获取 python 模块文档以填充到 /docs 文件夹中？

标签： pycharmpython-sphinx

解决方案

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

  1. 确保您尝试记录的模块有一个__init__.py文件，以便以后可以适当地导入它们。在您的情况下，您的tools和modules目录需要__init__.py文件。
  2. 确保您正在记录的所有模块都已使用正确的sphinx注释进行设置：

模块_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：

代码.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:

索引.rst：

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

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

   code.rst

如果您也想检查一下，这里有一个非常好的解释和教程。希望这会有所帮助！

推荐阅读