使用 sphinx autodoc、autosummary 和 autodoc_pydantic 隐藏模块路径

Question

我正在使用 Sphinx 和 autodoc 和 autosummary 使用 autodoc_pydantic 为 pydantic 模型生成文档。

模型非常复杂，在各种文件中有很多子模型，并且在单独的文件中包含用于验证的自定义类型。它也是一个更大的包的一部分，但我只想记录这个模块。

mypackage/
  __init__.py
  model/
    __init__.py
    model.py
    submodel.py
    types.py
model_doc/
  _build/
  _autosummary/
  conf.py
  index.rst

所以

model.py

看起来像这样：

from pydantic import BaseModel
from types import Language
# #: Supported languages
# Language = Literal['de', 'en']
from .submodel import SubModel

class Model(BaseModel):
  #: The language
  language: Language = 'en'
  #: submodel settings
  submodel: SubModel = SubModel()

我也

from .model import Model

在

__init__.py

.

现在我在

model_doc/conf.py

中设置了以下设置

sys.path.insert(0, os.path.abspath('..'))
import mypackage

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.intersphinx',
    'sphinxcontrib.autodoc_pydantic',
]

add_module_names = False
python_use_unqualified_type_names = True

autosummary_generate = True

autoclass_content = 'class'
autodoc_class_signature = 'separated'
autodoc_inherit_docstrings = False
autodoc_default_options = {
    'members': True,
    'undoc-members': True,
    'private-members': True,
}

autodoc_typehints_format = 'short'
autodoc_preserve_defaults = True
autodoc_type_aliases = {
    'Pattern': 're.Pattern',
    'Language': 'mypackage.model.types.Language',
}

我用

的简单

index.rst

渲染

.. autosummary::
   :toctree: _autosummary
   :recursive:

   mypackage.model

但是

add_omdule_names

和

python_use_qualified_type_names

都没有任何效果。我认为这与

autodoc_pydantic

有关，这看起来很重要，因为 pydantic 与元类等混为一谈，所以只是常规的

.. automodule::

没有使用默认值并产生奇怪的私有成员工件。

在渲染文档的侧边栏中我得到

mypackage.model
  mypackage.model.model
    mypackage.model.Model.language
    mypackage.model.Model.submodel
  mypackage.model.submodel
  mypackage.model.types

页面大致呈现为

mypackage.model.model

华丽的模型

Model

field

language

:

mypackage.model.types.Language

= 'en'

场

submodel

：

SubModel

=

SubModel(...)

1. 侧边栏和页面标题应该只显示模块或类名而不是包含包的完整路径。根据

   add_module_names = False

   ，但它不起作用

2. SubModel

   正确链接到该类的渲染页面，而类型应该在没有模块路径的情况下显示，并且还应该链接到正确的页面。根据

   autodoc_type_aliases = {...}

   和

   python_use_unqualified_type_names = True

   配置选项。请注意，它也不适用于像

   re.Pattern

   .
这样的 python 内部类型

我试过了

• (1)

  ..currentmodule::

  在

  index.rst

  中的各种组合，这没有帮助
• (1) 临时设置

  autosummary_generate = False

  并手动将

  .. currentmodule::

  指令插入存根页面，但没有用
• (2) 将

  from __future__ import annotations

  添加到所有源文件，这没有帮助

如果对这两个问题有任何建议，我将不胜感激。