变量和类属性未在Python Sphinx中使用自动模块显示 [英] Variables and class properties don't show using automodule in Python Sphinx

问题描述

我想知道为什么在Sphinx中使用automodule指令时为什么看不到类属性...即使一个属性有一个文档字符串.

I am wondering why I am not able to see class properties when using automodule directive in Sphinx...Even if a propertie has a docstring.

与Django设置常量相同，它们未显示.

Same thing with Django settings CONSTANTS, they don't shown.

我使用:

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

我将设置拆分为模块

设置

• _ init _.py
• installed_apps.py
• locale.py
• db.py
• cache.py
• stage_stable.py
• stage_test.py
• stage_dev.py
• ...
• templates.py

在 __ init __.py 中，我从其他文件导入所有内容，然后选择我在哪个阶段.

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

它与Django一起使用，简化了设置修改，并且...不适用于Sphinx.

It works with Django, simplifies settings modification and... Does not work with Sphinx.

推荐答案

文档字符串通常不适用于类属性，但是如果您将Sphinx的autodoc扩展名放在字段后，则可以.您还可以在字段之前使用以下特殊语法:

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"

要检查的其他事情是您在 conf.py 文件中列出了autodoc扩展名.查找 extensions = ["sphinx.ext.autodoc"] .(该列表可能包含多个扩展名.)

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:]我以前在错误的位置输入了文档注释.与文档字符串不同，#:注释必须在要注释的字段之前 .

[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:]由于上述不是问题，因此这是另一种可能性.在 .. automodule :: 之后使用的模块或软件包必须可用于您的文档.这意味着您需要确保将其位置添加到Python路径中.我的项目是这样设置的:

[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
            ...

在这种情况下，我需要将/my_package 添加到Python路径，以便可以访问 package .为此，我确保将其放置在 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('..','..')))

这实际上将 ./../.. 添加到Python路径，在我的示例中，该路径来自conf.py的 my_project 目录.(我也将其解析为一条绝对路径，以减少出现意外的可能性.)显然，您必须针对特定情况对此进行更改.

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.

希望这对您有所帮助.

这篇关于变量和类属性未在Python Sphinx中使用自动模块显示的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！