[Django]-Variables and class properties don't show using automodule in Python Sphinx

by

5👍

✅

docstrings normally don’t apply to class properties, but the autodoc extension to Sphinx is able to if you put it after the field. You can also use this special syntax, before the field:

#: Documentation for my_field.  You can
#: use one or more lines as well.
my_field = "something"

Other things to check are that you have the autodoc extension listed in the conf.py file. Look for extensions = ["sphinx.ext.autodoc"]. (The list may contain more than one extension.)

[edit:] I previously had the documentation comment in the wrong place. Unlike the docstring, the #: comments have to go before the field you are commenting.

[edit:] Since the above isn’t the problem, here’s another possibility. The module or package you use after .. automodule:: must be accessible to your documentation. This means you need to make sure you add its location to your Python path. My project is set up like this:

my_project/
    package/
        __init__.py
        ...
    doc/
        build/
            ...
        source/
            conf.py
            ...

In this case, I needed to add /my_package to the Python path so I could access package. To do so, I made sure this was in the top of my conf.py:

import sys, os   # I believe conf.py already imports sys,
import os.path   # os, and os.path.  But just in case, I
                 # list it here.

sys.path.insert(0, os.path.abspath(os.path.join('..','..')))

This effectively adds ./../.. to the Python path, which from conf.py in my example is the my_project directory. (I also resolve it to an absolute path just so there are fewer possibilities for surprises.) Obviously, you’d have to change this for your specific case.

I hope this helps you out.

👤dappawit

Leave a comment