标签: docstring

我想在Sublime Text 2中区分Python文档字符串和单行字符串.查看Python语言定义,我可以看到这一点,以及使用相同comment.block.python名称的撇号字符串的匹配定义.

<dict>
    <key>begin</key>
    <string>^\s*(?=[uU]?[rR]?""")</string>
    <key>end</key>
    <string>(?&lt;=""")</string>
    <key>name</key>
    <string>comment.block.python</string>
...

但是当我创建一个像这样的新颜色规则时:

<dict>
    <key>name</key>
    <string>Docstring</string>
    <key>scope</key>
    <string>comment.block.python</string>
    <key>settings</key>
    <dict>
        <key>foreground</key>
        <string>#008800</string>
    </dict>
</dict>

什么都没发生; 它们的颜色与单行字符串相同.

是否有可能做到这一点？如果是这样,我做错了什么？

我想在我的Python模块的文档字符串中添加一些元信息,例如作者,电子邮件,版本.有没有规范的方法呢？我搜索了很长一段时间,但在这里或网上找不到具有明确权限的东西.

PEP 426 - Python软件包2.0的元数据谈论它.它看起来像__author__,__version__其他一些被pydoc(V2.7)认可.此外,还有epydoc和sphinx-doc.

是否有标准方法在docstring中包含此类信息？还是作为全局变量？如果是,是否有可接受的关键字/变量名称列表？

例:

#########
# Parts
# <description>
#
"""Helper module for selling car parts on the web.
   Author: Sue Baru
   EMail: sb@carparts.com
   Version: 1.0
"""

更新

这不是一个真正的答案,但我最终使用了__author__'关键字'而没有别的.通过检入git仓库来完成版本控制.

multisql.py 的第一行：

#!/usr/bin/env python3
"""Execute SQL on multiple servers
"""
# -*- encoding: utf-8 -*-
import os
...

pylint警告：

[mutex@thinkpad multisql] @  $ pylint *.py
No config file found, using default configuration
************* Module setup
C:  1, 0: Missing module docstring (missing-docstring)

我究竟做错了什么？

我一直在使用此处描述的 Google Docstring 格式，但我想知道是否有一种商定的方法来记录已知类型的列表。

我一直在用

def function(a_list)
    """

    Args:
        a_list (list[dict]): a list of dictionaries
    """
    ...

这样对吗？

我尝试记录一个:rtype:docstring参数,返回一个生成器Node:

def __iter__(self):
    """iterate over node children

    :rtype: ???
    """
    for node in self.children.itervalues():
        yield node

什么:rtype:是应该是什么？generator of Node似乎不起作用.

我想在 sphinx 中包含乳胶文档。sphinx html build 不包括使用.. raw:: latex指令链接的乳胶文件。我有

这是我的目录结构

docs/
    source/
        importlatex.rst
        index.rst

    build/
    tex/
       texfile.tex

index.rst 好像

Welcome to documentation!
=========================

Contents:

.. toctree::
   :maxdepth: 2

   icnludelatex
   and-other-stuff

icnludelatex.rst 好像：

Include Latex
=============

.. raw:: latex
    :file: ../tex/texfile.tex

此参考提供了包含 html 的示例

.. raw:: html
    :file: inclusion.html

为什么会这样？

我正在尝试记录装饰器，但不确定文档字符串应该放在哪里。从技术上讲，它是包含我想要记录的参数的内部包装器，但用户将应用外部函数名称作为装饰器。

例如，

def change_case(func):
    """Does the doc string go here
    """
    def _wrapper(s, case=None):
        """Or, does the doc string go here?
        """
        if case == 'Upper':
            s = s.upper()
        elif case == 'Lower':
            s = s.lower()
        return func(s)

    return _wrapper

@change_case
def echo(s):
    return s

echo('Test', case='Upper')

在上面，文档字符串是否在 change_case() 或 _wrapper() 之后。我倾向于前者。

我正在使用 Google 风格的 python 文档字符串格式。有一个函数，输入参数可以是字典、列表或字符串。docstring中多种数据类型的格式是什么？

喜欢

Args:
    input (str, list, dict): input of this function

我想用以下标头编写一个函数：

def split_csv(file, sep=";", output_path=".", nrows=None, chunksize=None, low_memory=True, usecols=None):

如您所见，我使用的参数与中的几个参数相同pd.read_csv。我想知道（或要做）的是将与这些参数有关的文档字符串转发read_csv到我自己的函数中，而不必复制/粘贴它们。

编辑：据我了解，没有开箱即用的现有解决方案。因此，也许要按顺序建造一个。我的想法：

some_new_fancy_library.get_doc(for_function = pandas.read_csv,for_parameters = ['sep','nrows']) 将输出：

{'sep': 'doc as found in the docstring', 'nrows' : 'doc as found in the docstring', ...}

然后将字典的值插入到我自己的函数的文档字符串中就可以了

干杯

为字典的键添加文档字符串的推荐方法是什么？我正在使用 python 2.7 和 Sphinx。

例如，在下面的代码中，我应该如何提及 my_dict 的键“a”和“b”？（但也许没有必要详细介绍）：

def my_func(my_dict):
    """
    :param dict {'a': float, 'b': str} my_dict: description of param
    """
    pass

我的 Pycharm 编辑器似乎无法识别上面的实现

编辑：我也读过这篇文章，但答案没有提到如何指定键的“名称”