python-2.7 - 我应该如何使用 Google 风格的 Sphinx 记录列表、选项和 yield ？

Question

关闭。这个问题是 opinion-based 。目前不接受答案。

---

想要改进这个问题吗？更新问题，以便 editing this post 可以用事实和引文来回答它。 .

已关闭 5 年前。

Improve this question

如何使用 Sphinx-Napoleon 指示 Google 风格文档字符串上的列表类型、可选参数和生成器的返回类型？

我已经尝试过

List[type]
list of type

Optional[type]
type, optional

和

Yields:
   type: 

分别；但所有这些都会产生不令人满意的输出，与生成的文档的其余部分不一致。例如

Optional[type]

只是给出

Optional[type]

没有任何 type 的链接.

我尝试了每个内置主题并遇到了相同的问题。

我应该如何使用 Sphinx-Napoleon 的 Google 风格文档字符串来记录这些元素？

Answer 1

我知道这已经很老了，但是你看过this example吗？ ？特别是行:

def __init__(self, param1, param2, param3):
        """Example of docstring on the __init__ method.

        The __init__ method may be documented in either the class level
        docstring, or as a docstring on the __init__ method itself.

        Either form is acceptable, but the two should not be mixed. Choose one
        convention to document the __init__ method and be consistent with it.

        Note:
            Do not include the `self` parameter in the ``Args`` section.

        Args:
            param1 (str): Description of `param1`.
            param2 (:obj:`int`, optional): Description of `param2`. Multiple
                lines are supported.
            param3 (:obj:`list` of :obj:`str`): Description of `param3`.

        """
        self.attr1 = param1
        self.attr2 = param2
        self.attr3 = param3  #: Doc comment *inline* with attribute

        #: list of str: Doc comment *before* attribute, with type specified
        self.attr4 = ['attr4']

        self.attr5 = None
        """str: Docstring *after* attribute, with type specified."""