如何使用带 Sphinx 的自动模块删除静态 class 变量？

Question

我目前正在使用 Sphinx（第一次使用它）为我的模块构建文档，我有一些 classes，其中有一些 class 变量用默认值初始化.

例如：

class ConfigSettings(object):
    """Class that manages a config file
    """    
    #: Contains the path to the config file (root dir of module)
    path = Path(util.getAbsCurrentPath('configfile.ini'))

构建文档时，会评估变量并打印我不想要的文件的完整路径（出于安全原因）。有没有办法不显示变量值，而只显示使用 Sphinx 的注释？

我尝试了 .. autoclass: 和 .. autodata: 的各种组合，但到目前为止，其中 none 有效...

这是我目前在构建文件中的内容：

Config module
----------------------------

.. automodule:: lib.config
   :members:
   :undoc-members:
   :show-inheritance:

Answer 1

您可以通过在导入时不评估路径来解决该问题。我认为最好的方法是使用 classproperty.

例如：

class ConfigSettings(object):
    @classproperty
    def path(cls):
        return Path(util.getAbsCurrentPath('configfile.ini'))

Answer 2

使用 Sphinx 指令的最简单方法是使用注释或排除成员。

除非严格要求阻止变量在模块导入时自初始化，否则更改 Python 源是不正确的，因为您希望以它的方式呈现它。如果您的 Python 源代码是正确的，则调整您的 .rst 文件以自定义演示文稿。

your_module.py

from pathlib import Path


class YourClass:

    #: This comment is documented with the member.
    path = Path('your_path', 'configfile.ini')

your_module.rst（显示 2 种可能的方式）。

your_module
===========

.. automodule:: your_module
    :exclude-members: YourClass

    .. autoclass:: YourClass
        :exclude-members: path

        In this example you use an annotation while excluding from autoclass.

        .. autoattribute:: path
            :annotation: ='write your path here'

    .. autoclass:: YourClass
        :noindex:
        :exclude-members: path

        In this example you simply exclude from autoclass.

结果：

如何使用带 Sphinx 的自动模块删除静态 class 变量？

How to remove static class variable using automodule with Sphinx?

python

docstring

member

python-sphinx

autodoc