Sphinx includes private attributes even though not instructed to

Question

I did not include the :private-members: option anywhere, but Sphinx still includes private attributes in the docs for the class. What am I doing wrong?

MWE:

mypackage/foo.py:

class MyClass(object):
    """A class.

    Attributes
    ----------
    attr1 : float
        Attribute 1.
    attr2 : float
        Attribute 2.
    _private1 : float
        Private attribute 1.
    _private2 : float
        Private attribute 2.
    """
    pass

index.rst:

.. toctree::
    :maxdepth: 2
    :caption: Table of Contents

    foo

foo.rst:

``foo`` Module
==============

.. automodule:: mypackage.foo
    :members:

conf.py:

# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.

import os
import sys
sys.path.insert(0, os.path.abspath('../'))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
]

source_suffix = '.rst'

master_doc = 'index'

language = 'en'

Rendered html:

score 2 · Accepted Answer · answered Jun 08 '22 at 13:29

2

The absence of :private-members: only takes effect for members that sphinx finds by parsing the Python code. For example:

class MyClass(object):
    """A class"""
    attr1 = 42  #: Attribute 1.
    attr2 = 43  #: Attribute 2.
    _private1 = 44  #: Private attribute 1.
    _private2 = 45  #: Private attribute 2.

In this case, it won't document _private1 and _private2 (without :private-members:).

In you case, however, _private1 and _private2 are just text inside a doc string. I doubt even that sphinx in that case knows that they are attributes of the class.

answered Jun 08 '22 at 13:29

Antonis Christofides

6,990
2
39
57

I think Sphinx _does_ recognize those are attributes from my docstring, because (a) they're formatted like attributes in the HTML, and (b) if I add your code but keep my docstring, I get warnings like `duplicate object description of mypackage.foo.MyClass.attr1`. – LarrySnyder610 Jun 08 '22 at 16:27
My attributes are really instance attributes, so I can't initialize them in the class the way you did. Is there a way to include them in a way that Sphinx will find them and parse them correctly, i.e., omitting the private attributes? – LarrySnyder610 Jun 08 '22 at 16:28
Well I guess one workaround is just to delete the private attributes from my docstring... – LarrySnyder610 Jun 08 '22 at 16:42
If you don't want these private members documented, why are you documenting them? It doesn't make much sense. If they are an implementation detail that you want to document for the class maintainer but you don't want to expose this information to the class user, it would probably be better to use plain comments. – Antonis Christofides Jun 08 '22 at 18:43
AFAICS you can document instance attributes with the smart comments. In the autodoc documentation, [just above "Configuration"](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration), there's an example that shows the various options for doing so. – Antonis Christofides Jun 08 '22 at 18:48
Yes, I wanted to document for the class maintainer. I'll follow your suggestion. Thanks for the additional link -- that helps too. – LarrySnyder610 Jun 08 '22 at 20:24

Sphinx includes private attributes even though not instructed to

1 Answers1