如何將特定模塊的 `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:: 。 這使您可以指定簽名和完全限定名稱 - 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.

給出以下結果：