标签: docstring

我正在使用 python 3.1。

是否可以为单个模块或函数创建超过 1 个文档字符串？我正在创建一个程序，并且打算拥有多个文档字符串，每个文档字符串都有一个类别。我打算向其他人提供该程序，以便他们可以使用它，并且为了让程序员和非程序员都轻松使用它，我在程序本身中放置了对文档字符串的引用。

更具体地说，我在程序/模块中有一个菜单作为界面，其中一个选项将允许访问模块文档字符串以获取程序文档。因此，如果可能的话，我想制作多个文档字符串来对不同类型的文档进行分类。因此，如果用户想查看文档的某些部分，会更容易。

例如。第一个文档字符串包含有关如何使用该程序的说明。第二个文档字符串包含有关程序的一部分如何工作的信息。第三个文档字符串包含有关其他部分如何工作的信息。ETC。

这可能吗？如果是这样，你如何引用它们？

更新：添加了评论。

我最初的想法是实际上拥有多个文档字符串，其含义如下：

def foo():
    """docstring1: blah blah blah"""
    """docstring2: blah blah blah"""
    pass # Insert code here

然后我可以使用一些代码来引用每个文档字符串。那么，我猜这是不可能的？

我正在尝试制作一个将接受替换字段的文档字符串，如下所示

def run_tests(args):
    """run tests on methods in {0}

    usage: {0} --tests
    """.format(__file__)
    pass

但是当我help(run_tests)在解释器中运行时，我没有得到文档字符串。如果我删除 {} 和 .format() 文档字符串将按预期返回。

我想看到类似的输出：

Help on function run_tests in module myfile:

run_tests(args)
    runs tests on methods in myfile.py

    usage:  myfile.py --tests

python3 有没有办法做到这一点？

我有一堂课MyClass：

class MyClass(object):
    def __init__(self):
        pass

    def my_function(self, x):
        # MyClass.my_function.__doc__ is not writable!
        # Otherwise, I could just set it here.
        Origin.func(self, x)

该类借用Origin：

class Origin(object):    
    def func(obj, x):
        """This is a function
        """
        # do stuff
        pass

如何自动将文档字符串从 Origin.func 复制到 MyClass.my_function 以便 Sphinx Autodoc 识别它？我怎样才能将原始文档字符串扩展几个单词？

编辑：

Afaik，我不能__doc__在函数定义之后进行更改，因为那时 Sphinx 找不到它。或者如果是这样，“docfix”会去哪里？

好吧，这个问题可能已经在某个地方得到了回答，但我的 Google-fu 还没有找到正确的关键字组合。

我有一个接受字符串的函数，但是当我传递 None 时，Pycharm 的检查会标记类型错误。这是 linter 中的错误吗？None 算作字符串吗？我知道我可以使用空字符串调用该函数，但我认为我也应该能够使用 None 。

def my_func(some_str):
""" does something
Arguments:
some_str (str): a string
"""
    # do something

...

my_func(None)  <-- throws Expected type 'str', got 'None' instead

在Python中，除了当前函数/方法体中引发的异常之外，我们是否应该在文档字符串中记录可以在其他函数/类中引发的异常？

观察：我正在考虑 Google Python 文档字符串风格https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

我已经很长时间没有使用 Java 了，但在那里你会明确地说你的方法可以使用“throws”关键字引发什么样的异常。

例如。：

class MyException(Exception):
    pass

class A(object):
    def foo(self):
       """This class does foo

       Returns:
           Int: The number of foo.

       Raises:
            MyException - In case something happen
       """
       if True:
           raise MyException
       return 0

class B(object):
    def __init__(self):
        self._a = A()

    def bar(self):
        """This class does bar
        Returns:
            Int: number of bar
        Raises:
             MyException ????? Should this be here?
        """

        return self._a.foo()

我知道 Racket 没有像许多其他语言那样具有“文档字符串”，但考虑到在源代码中记录事物是多么方便，我想在 Racket 中近似类似的东西。

当我第一次了解 Scribble 和 #langs 时，我认为可以做如下事情：

#lang racket
#lang scribble

...然后在 Racket 中使用 Scribble 中的文档字符串编写代码。但这行不通，可能是因为“语言不会组合”。

#lang racket
(require scribble/manual)

@racket['hi]

结果是：

my-source.rkt:4:0: @racket: unbound identifier

我发现这似乎很引人注目，因为听起来它允许您在合同scribble/srcdoc之上搭载文档，这些文档已经作为一种最小（通常是模块级）文档，当然除了提供运行时检查之外。到目前为止我还没能让它工作，但我认为在这里询问它会更有用，而不是再折腾几个小时。就其价值而言，这就是我目前所看到的：

#lang racket
(require scribble/srcdoc
         (for-doc scribble/base scribble/manual))

(provide
 (proc-doc/names fib
                 (-> integer? integer?)
                 (n)
                 @{Computes the @racket[n]th Fibonacci number}))

(define (fib n)
  (if (< n 2)
      n
      (+ (fib (- n 1))
         (fib (- n 2)))))

结果是：

my-source.rkt:6:1: proc-doc/names: bad syntax
  in: (proc-doc/names fib (-> integer? integer?) …

我有一堂课：

class Holiday(ActivitiesBaseClass):
    """Holiday is an activity that involves taking time off work"""

    Hotel = models.CharField(max_length=255)
    """ Name of hotel """

我可以通过键入以下内容来打印类文档字符串：

print(Holiday.__doc__)

这输出为：

Holiday is an activity that involves taking time off work 

如何打印属于 Class 属性/元素的 Hotel 的文档字符串？

我试过的

print(Holiday.Hotel.__doc__)

返回：

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

我也试过这个help()功能无济于事。

NB

Sphinx 似乎能够提取类属性的文档字符串并将它们包含在 readthedocs 中，所以我希望有一种方法

我已经使用 Google 风格的 Python 文档字符串格式有一段时间了。我处理没有参数的函数/方法的方式突然对我来说看起来不正确。我做了一些搜索，但在网上找不到任何指定如何处理这种情况的信息。

当没有退货时，我见过None二手货，我对此表示同意，因为从技术上讲，这就是退货的原因。但是，使用Noneargs 可能意味着实际上有一个参数的类型预计为：NoneType。

目前，我一直在做的事情看起来像这样：

def foo():
    """
    blah blah blah

    Args:
        None
    Returns:
        The number 5
    """
    return 5

我的问题是，我应该使用哪种格式（我更喜欢总是有一个Args部分）？或者也许我目前的方法并没有那么糟糕，并且是常见的做法。

其他一些候选者（如果您认为有更好的格式，请随时提供您自己的候选者）：

def foo():
    """
    blah blah blah

    Args:

    Returns:
        The number 5
    """
    return 5

def foo():
    """
    blah blah blah

    Args:
        No arguments
    Returns:
        The number 5
    """
    return 5

def foo():
    """
    blah blah blah

    Returns:
        The number 5
    """
    return 5

Numpy 文档字符串指南说：

冒号前面必须有空格，如果类型不存在，则省略。

并举了一个例子：

Parameters
----------
x : type
    Description of parameter `x`.
y
    Description of parameter `y` (with type not specified)

另一方面， PEP8字面意思是冒号前的空格是错误的：

# Wrong:

code:int  # No space after colon
code : int  # Space before colon

我知道这适用于代码，而不适用于文档字符串，但为什么不保持一致？

题

在冒号前放置一个空格的动机是什么？

它似乎违反了排版规则和 python 约定（或至少是直觉）。

我对记录类的 PEP257 标准有点困惑。

它说，“一个类的文档字符串应该总结它的行为并列出公共方法和实例变量”

但它也说所有函数都应该有 dosctrings（当然，我想要，这样 help() 工作）。

但这似乎涉及重复，即

class foo:
    """A class

    Attributes
    ----------
    bar : str 
        A string

    Methods
    -------
    __init__(fish):
        Constructor, fish is a str which self.bar will be set to.
    baz():
        A function which does blah

    """

    def __init__(self, fish):
    """
    Constructs an XRTProductRequest object.

    Parameters
    ----------
    fish : str
        A string, which the self.bar attribute will be set to.
    """
    etc...

这很容易出错，因为这意味着当我意识到__init__还需要接收一个 int 时，我必须记住在 2 个地方更新文档，我可以保证我会忘记。

它还使 pydoc 输出重复：它打印我的类文档字符串，然后说“此处定义的方法”并继续通过它们自己的文档字符串列出所有方法。

那么，这个重复真的是 PEP257 的一部分，还是我误读了它？我是否应该删除类文档字符串的“方法”部分，因为每个方法都有自己的文档字符串？或者这种重复真的是标准的一部分吗？

TIA