使用 Sphinx 时，如何记录没有文档字符串的成员? [英] When using Sphinx, how can I document members that don't have docstrings?

问题描述

我正在为我发布的包编写文档，我发现你的文档越详尽，人们就越容易找到你的包(废话).实际上，我很高兴地编写代码的所有功能和细节.

然而，我对如何为类级变量编写与 Sphinx 兼容的文档感到非常困惑.特别是，我有一些

最后一点:这可能会强制调整您以前用于在源代码中注释变量的一些约定.此外，如果使用注释，您将不希望将该成员包含在 autodata 或 automodule 中，以避免它被包含两次.

I'm writing documentation for package I've published, and I find the more thorough your documentation, the easier people find your package to use (duh). I'm actually having a lot of fun lovingly writing up all the features and details of my code.

However, I'm completely flummoxed by how to write Sphinx-compatible documentation for class-level variables. In particular, I've got some enum classes I'd like to document, but for the life of me I can't figure out a way to attach documentation to the enum values. The result is I've got these long and awkward sections of my documentation where there's no documentation except variable names.

I realize using straight docstrings is out of the question because variables don't have docstrings, but surely Sphinx has some sort of functionality around this? Otherwise, how would people document publicly visible values like constants?

解决方案

While it's true Python variables can't have docstrings. Using Sphinx autodoc extension, the autodata and autoattribute directives allow documenting variables and constants. Notice the use is different in case of a module level variable or a class member.

Additionally, should you want to arbitrate a value for the member in the documentation that is different from the programmatic value, the best way is using annotations.

autodata and autoattribute support the annotation option.

Sphinx can pick up comments on variable declarations and include them in the documentation (while those comments aren't docstrings they will be rendered in the documentation). Let's look at a minimal working example:

Source file your_module_name.py:

"""This modules documentation."""

ONE_CONSTANT = "A constant value."
"""Turns out the comment is rendered as a docstring if we put it underneath."""

#: Lets try it like this
TWO_CONSTANTS = 2000


class OneClass:
    """Commenting members of a class."""

    #: Lets try the third comment like this.
    THREE_CONSTANTS = 3000

    #: Lets try the forth comment like this.
    FOUR_CONSTANTS = 4000

Corresponding your_module_name.rst:

your\_module\_name module
=========================

.. automodule:: your_module_name
   :members: ONE_CONSTANT, TWO_CONSTANTS

   .. autodata:: ONE_CONSTANT
      :annotation: =this annotation

   .. autoclass:: OneClass
      :members:
      :undoc-members:
      :show-inheritance:

The resulting HTML:

Final note: This may force adapting some conventions you previously used for commenting variables in your source code. Also, if using annotations you'll want to not include that member in autodata or automodule to avoid it being included twice.

这篇关于使用 Sphinx 时，如何记录没有文档字符串的成员?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！