autodoc-traits

autodoc-traits 是一个基于 sphinx.ext.autodoc 的 Sphinx 扩展，它利用 Traitlets 的配置来更好地记录类。 autodoc-traits 提供了 Sphinx 指令 autoconfigurable（用于类）和 autotrait（用于基于 Traitlets 的配置选项）。

sphinx.ext.autodoc 提供的指令 [automodule][]，可以概述类，当启用 autodoc-traits 时，将使用 autoconfigurable 而不是 autoclass，以处理具有基于属性的配置的类。同样，sphinx.ext.autodoc 提供的 autoclass 指令将使用 autotrait 而不是 autoattribute，如果配置为显示通常不显示的 Traitlets 属性。

autoattribute 指令将提供类似于 trait c.SampleConfigurable.trait = Bool(False) 的标题，并将其作为文档字符串，使用属性配置的帮助文本。

如何使用它

1. 安装 autodoc-traits

   pip install autodoc-traits
   

2. 在 Sphinx 项目的 conf.py 文件中配置 Sphinx 以使用 autodoc_traits 扩展

   # -- General Sphinx configuration --------------------------------------------
   # ref: https://sphinx-doc.cn/en/master/usage/configuration.html#general-configuration
   #
   extensions = [
       "autodoc_traits",
       # sphinx.ext.autodoc will be registered by autodoc_traits,
       # but can safely be registered again.
       # ...
   ]
   

3. 像 automodule 这样的 sphinx.ext.autodoc Sphinx 指令，用于记录类，或者使用 autodoc_traits 提供的 autoconfigurable 来记录可配置的 Traitlets 类，或者使用 autodoc_traits 提供的 autotrait 来记录单个 Traitlets 配置选项

   从 .rst 文档

   .. automodule:: sample_module
      :members:
   
   .. autoconfigurable:: sample_module.SampleConfigurable
   
   .. autotrait:: sample_module.SampleConfigurable.trait
   

与 MyST 解析器一起使用

虽然可以使用 myst-parser，但 sphinx.ext.autodoc 的指令会发出未解析的 rST，这迫使我们必须在 rST 上下文中解析 autodoc 指令。

从 .md 文档，与 myst-parser 一起

```{eval-rst}
.. autoconfigurable:: sample_module.SampleConfigurable
```

因此，Python 文档字符串也必须以 rST 格式。关于此问题的解决方案可以在 executablebooks/team-compass issue #6 中找到。