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

Question

如何更改add_module_names特定False模块？

我有以下结构：

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

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

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

Answer 1

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

解决方案是使用域指令显式声明您想要的成员，在这种情况下为.. py:function::. 这使您可以指定签名和完全限定名称 - PEP 3155。缺点是您不会使用autodoc 指令，因此您无法从 Python 源代码中自动提取文档字符串。根据您决定放置的位置.. py:function::，可能需要在特定指令中使用:noindex:-: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.

给出以下结果：