如何将特定模块的 `add_module_names` 更改为 `False`？

Question

如何将特定模块的 add_module_names 更改为 False？

我有以下结构：

src/
    / _foo
       some_file.py
    / bar
       some_other_file.py

我希望 _foo 模块中带有 .. autofunction:: 的所有函数文档都隐藏模块名称，而 bar 模块的所有函数都显示名称。

有没有办法让我按模块执行此配置，甚至为每个功能单独执行此配置？

Answer 1

add_module_names 布尔值是 conf.py 中的常规配置设置。它反映了您在项目范围内选择使用对象呈现模块名称，它不能针对特定模块进行更改。可以实施规则的例外，但解决方法需要一些额外的编写。

解决方案是使用域指令显式声明您想要的成员，在本例中为 .. py:function::. This lets you specify the signature and the fully qualified name - PEP 3155. The drawback is you won't be using an autodoc directive so you loose the automatic extraction of docstrings from your Python source code. Depending on where you decide to place .. py:function:: it may be necessary to use :noindex: and :exclude-members: 在特定指令中 - 用法如示例所示。

请注意，最后一个示例仍然需要前导 . 点，否则 Sphinx 将按照 add_module_names = True.

指定的完全限定名称添加前缀

两个简单的示例文件，bar.some_other_file.py:

"""bar.some_other_file module docstring."""

def some_other_function():
    """some_other_function docstring."""

和_foo.some_file.py:

"""_foo.some_file module docstring."""

def some_function(argument_example="a string"):
    """some_function docstring."""

使用以下 .rst 比较两种情况：

_foo costum module name
-----------------------

.. automodule:: _foo.some_file
    :members:
    :undoc-members:
    :exclude-members: some_function

    .. autofunction:: some_function

    .. py:function:: .some_function(argument_example="a string")
        :noindex:

        Example without any module name.

bar costum module name
----------------------

.. automodule:: bar.some_other_file
    :members:
    :undoc-members:
    :exclude-members: some_other_function

    .. autofunction:: some_other_function

    .. py:function:: bar.some_other_file.some_function(argument_example="a string")
        :noindex:

        Example with a different qualified name.

给出以下结果：

如何将特定模块的 `add_module_names` 更改为 `False`？

How can I change `add_module_names` to `False` for specific modules?

python

qualified-name

python-sphinx

autodoc