将Sphinx Autodoc与手动文档相结合

Question

我目前正在编写一份参考文档，该文档最初是用.. class::手动记录的。模块中的所有类都是这样记录的。

然而，最近有必要对文档进行一些自动化，例如每个类的show-inheritance，但现在的问题是如何将当前的手动文档与autodoc结合起来。

我试着简单地用.. autoclass::替换.. class::，但这导致了一个输出，其中手动键入到文档中的描述和参数描述(而不是从文档字符串生成的(不会在输出中呈现。有人能建议如何解决这个问题吗？

以下是更多详细信息：

看看这个：

.. autoclass:: wagtail.blocks.CharBlock
:show-inheritance:
.. class:: CharBlock
A single-line text input. The following keyword arguments are accepted in addition to the standard ones:
:param required: If true (the default), the field cannot be left blank.
:param max_length: The maximum allowed length of the field.
:param min_length: The minimum allowed length of the field.
:param help_text: Help text to display alongside the field.
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.

输出：在此处输入图像描述

问题是我必须重复类名，这会让文档的用户感到困惑。autoclass将不呈现参数，因此需要class。我需要autoclass能够显示类(Bases(的继承。所以我不知道是否有一个指令可以在不必提及类名的情况下执行class的函数，或者是否有任何方法可以强制类不接受任何参数？

我希望这一点更清楚。感谢

Answer 1

有些事情可以使用autodoc(在这种情况下，它只是:show-inheritance:(；手动"；文档(非文档字符串中的内容(。

删除.. class::，并确保.. autoclass::行之后的所有行具有相同的缩进。我认为这应该产生你想要的输出。

.. autoclass:: wagtail.blocks.CharBlock
:show-inheritance:
A single-line text input. The following keyword arguments are accepted in addition to the standard ones:
:param required: If true (the default), the field cannot be left blank.
:param max_length: The maximum allowed length of the field.
:param min_length: The minimum allowed length of the field.
:param help_text: Help text to display alongside the field.
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.