Question

我正在尝试使用sphinx为我的python包生成文档。我在所有函数中都包含了很好的文档字符串。我已调用sphinx-quickstart来创建模板，填入模板，并调用make html来生成文档。我的问题是我的python模块中也有注释也出现在渲染文档中。注释不在函数内，而是作为.py文件顶部的标题。我需要有这些评论块并且无法将其删除，但我不希望它们显示在我的文档中。

我目前正在使用automodule将所有功能从模块中拉出来。我知道我可以使用autofunction逐个获取各个函数，这样可以避免文件头，但是我有很多函数，必须有更好的方法。

如何调整我的conf.py文件或其他内容以使用automodule，但只能选择函数而不是函数之外的注释？

这就是我的.py文件：

"""
This code is a part of a proj repo.

https://github.com/CurtLH/proj

author: greenbean4me
date: 2018-02-07
"""

def hit(nail):

    """
    Hit the nail on the head

    This function takes a string and returns the first character in the string

    Parameter
    ----------
    nail : str
       Can be any word with any length

    Return
    -------
    x : str
       First character in the string

    Example
    -------
    >>> x = hit("hello")
    >>> print(x)
    >>> "h"
    """

    return nail[0]

这是我自动生成的文档：

Auto-Generated Documentation

This code is a part of a proj repo.

https://github.com/CurtLH/proj

author: greenbean4me date: 2018-02-07

hammer.hit(nail)

    Hit the nail on the head

    This function takes a string and returns the first character in the string

    nail : str
        Can be any word with any length

    x : str
        First character in the string

    >>> x = hit("hello")
    >>> print(x)
    >>> "h"

有关更全面的示例，请查看GitHub上的此示例repo：https://github.com/CurtLH/proj

Answer 1

据我所知，没有办法配置autodoc不这样做。

但是，有一个简单的解决方法：在模块顶部添加一个空文档字符串。

""""""  # <- add this
"""
This code is a part of a proj repo.

https://github.com/CurtLH/proj

author: greenbean4me
date: 2018-02-07
"""

它几乎不会引人注意，并且会欺骗autodoc而不显示模块的真实文档字符串。

使用sphinx生成文档时排除标题注释

1 个答案: