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:

Antonis Christofides · Accepted Answer · 2022-06-08 13:29:42Z

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 8, 2022 at 13:29

Antonis Christofides

7,0483 gold badges49 silver badges67 bronze badges

Sign up to request clarification or add additional context in comments.

6 Comments

LarrySnyder610 Over a year ago

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 Over a year ago

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 Over a year ago

Well I guess one workaround is just to delete the private attributes from my docstring...

Antonis Christofides Over a year ago

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 Over a year ago

AFAICS you can document instance attributes with the smart comments. In the autodoc documentation, just above "Configuration", there's an example that shows the various options for doing so.

|

Collectives™ on Stack Overflow

Sphinx includes private attributes even though not instructed to

1 Answer 1

6 Comments

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

6 Comments

Related