python sphinx variables and class properties in automodule

问题

I am wondering why I am not able to see class properties when using automodule directive in sphinx...

even if properties has docstring

same thing with django settings CONSTANTS, they are not shown.

I use:

.. automodule:: settings
   :members:
   :show-inheritance:
   :undoc-members:

I split settings into module

settings

__init__.py
installed_apps.py
locale.py
db.py
cache.py
stage_stable.py
stage_test.py
stage_dev.py
...
templates.py

and in __init__.py i import everything from other files and select on which stage am I

it works with django, simplifies settings modification and... does not work with sphinx :{

回答1:

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.

来源：https://stackoverflow.com/questions/5319484/python-sphinx-variables-and-class-properties-in-automodule

标签

python

django

documentation

module

python-sphinx