CODEWITHSUNDEEP
pythonpython-sphinx
CurtLH
CurtLH

Reputation: 2417

Exclude header comments when generating documentation with sphinx

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

Upvotes: 0

Views: 1590

Answers (1)

Aran-Fey
Aran-Fey

Reputation: 43326

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.

Upvotes: 4

Related Questions