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

Question

I am trying to use sphinx to generate documentation for my python package. I have included well documented docstrings within all of my functions. I have called sphinx-quickstart to create the template, filled in the template, and called make html to generate the documentation. My problem is that I also have comments within my python module that are also showing up in the rendered documentation. The comments are not within the functions, but rather as a header at the top of the .py files. I am required to have these comment blocks and cannot remove them, but I don't want them to show up in my documentation.

I'm current using automodule to pull all of the functions out of the module. I know I can use autofunction to get the individual functions one by one, and this avoids the file headers, but I have a lot of functions and there must be a better way.

How can I adjust my conf.py file, or something else to use automodule , but to only pick up the functions and not the comments outside of the functions?

This is what my .py file looks like:

"""
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]

This is my the auto-generated documentation looks like:

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"

For a more comprehensive example, check out this example repo on GitHub: https://github.com/CurtLH/proj

Answer 1

As far as I know, there is no way to configure autodoc not to do this.

There is, however, a simple workaround: Adding an empty docstring at the top of your module.

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

https://github.com/CurtLH/proj

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

It's barely noticeable, and will trick autodoc into not displaying your module's real docstring.