Руководство по документации NumPy/SciPy

При использовании Sphinx в сочетании с соглашениями NumPy, необходимо использовать расширение numpydoc, чтобы ваши строки документации обрабатывались корректно. Например, Sphinx извлечёт раздел Parameters из вашей строки документации и преобразует его в список полей. Использование numpydoc также поможет избежать ошибок reStructuredText, которые генерирует обычный Sphinx при столкновении с соглашениями NumPy о строках документации, такими как заголовки разделов (например, -------------), которые Sphinx не ожидает найти в строках документации.

Некоторые функции, описанные в этом документе, требуют недавней версии numpydoc. Например, раздел Возвращаемые значения был добавлен в numpydoc версии 0.6.

Доступно по адресам:

Обратите внимание, что при документировании внутри NumPy нет необходимости в import numpy as np в начале примера. Однако некоторые подмодули, такие как fft, не импортируются по умолчанию, и вам нужно явно их включить:

import numpy.fft

после чего вы можете использовать его:

np.fft.fft2(...)

Для удобства ниже приведен стандарт форматирования с примером

Руководство по строкам документации numpydoc

Руководство по документации NumPy/SciPy
- Руководство по строкам документации numpydoc
Исходный код примера
Отображенный пример

Этот документ описывает синтаксис и лучшие практики для строк документации, используемых с расширением numpydoc для Sphinx.

Примечание

Для сопровождающего примера см. example.py.

Обзор

Мы в основном следуем стандартным соглашениям стилей Python, описанным здесь:

Дополнительные PEPы, представляющие интерес в отношении документирования кода:

Используйте проверку кода:

pylint
pyflakes
pep8.py
flake8
плагин vim-flake8 для автоматической проверки синтаксиса и стиля с помощью flake8

Соглашения об импорте

Следующие соглашения об импорте используются во всем исходном коде NumPy и в документации:

import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt

Не сокращайте scipy. В реальном мире нет мотивирующих случаев для сокращения, поэтому мы избегаем этого в документации, чтобы избежать путаницы.

Стандарт строк документации

Строка документации (docstring) — это строка, описывающая модуль, функцию, класс или определение метода. Строка документации — это специальный атрибут объекта (object.__doc__) и, для согласованности, окружена тройными двойными кавычками, например:

"""This is the form of a docstring.

It can be spread over several lines.

"""

NumPy, SciPy и scikits следуют общему соглашению о строках документации, обеспечивающему согласованность, а также позволяющему нашей системе создавать хорошо отформатированные справочные руководства. Этот документ описывает текущий консенсус сообщества по такому стандарту. Если у вас есть предложения по улучшению, опубликуйте их на списке рассылки numpy-discussion.

Наш стандарт строк документации использует синтаксис reStructuredText (reST) и рендерится с помощью Sphinx (препроцессора, понимающего особый стиль документации, который мы используем). Хотя доступен богатый набор разметки, мы ограничиваемся очень базовым подмножеством, чтобы обеспечить строки документации, которые легко читаются в текстовых терминалах.

Основной принцип заключается в том, что читатели текста должны иметь приоритет над тем, чтобы изменять строки документации для создания красивого вывода для наших инструментов. Вместо того, чтобы жертвовать читабельностью строк документации, мы написали препроцессоры, помогающие Sphinx в его задаче.

Длина строк документации должна быть ограничена 75 символами, чтобы облегчить чтение строк документации в текстовых терминалах.

Разделы

Строка документации состоит из нескольких разделов, разделенных заголовками (кроме предупреждения о устаревании). Каждый заголовок должен быть подчеркнут дефисами, и порядок разделов должен быть согласован с описанием ниже.

Разделы строки документации функции:

Краткое описание

Однострочное описание, которое не использует имена переменных или имя функции, например:
```
def add(a, b):
   """The sum of two numbers.

   """
```
Подпись функции обычно находится путём интроспекции и отображается функцией help. Для некоторых функций (особенно написанных на C) подпись недоступна, поэтому нам нужно указать её в первой строке строки документации:
```
"""
add(a, b)

The sum of two numbers.

"""
```

Предупреждение о устаревании

Раздел (используйте, если применимо) для предупреждения пользователей о том, что объект устарел. Содержимое раздела должно включать:
- В какой версии NumPy объект был устарел и когда он будет удален.
- Причина устаревания, если эта информация полезна (например, объект заменен, дублирует функциональность, найденную где-то еще и т. д.).
- Новый рекомендуемый способ получения той же функциональности.
В этом разделе должен использоваться директива deprecated Sphinx вместо заголовка раздела с подчеркиванием.
```
.. deprecated:: 1.6.0
          `ndobj_old` will be removed in NumPy 2.0.0, it is replaced by
          `ndobj_new` because the latter works also with array subclasses.
```
Подробное описание

Несколько предложений, дающих подробное описание. Этот раздел должен использоваться для уточнения функциональности, а не для обсуждения деталей реализации или теоретических основ, которые следует исследовать в разделе Примечания ниже. Вы можете ссылаться на параметры и имя функции, но описания параметров по-прежнему должны быть в разделе Параметры.
Параметры

Описание аргументов функции, ключевых слов и их соответствующих типов.
```
Parameters
----------
x : type
    Description of parameter `x`.
y
    Description of parameter `y` (with type not specified)
```
Переменные заключите в одинарные обратные кавычки. Двоеточие должно предшествовать пробелу или быть опущено, если тип отсутствует.

Для типов параметров будьте максимально точны. Ниже приведены несколько примеров параметров и их типов.
```
Parameters
----------
filename : str
copy : bool
dtype : data-type
iterable : iterable object
shape : int or tuple of int
files : list of str
```
Если не нужно указывать ключевой аргумент, используйте optional:
```
x : int, optional
```
Дополнительные ключевые параметры имеют значения по умолчанию, которые отображаются в качестве части подписи функции. Они также могут быть подробно описаны в описании:
```
Description of parameter `x` (the default is -1, which implies summation
over all axes).
```
Когда параметр может принимать только одно из фиксированного набора значений, эти значения могут быть перечислены в фигурных скобках, причем значение по умолчанию появляется первым:
```
order : {'C', 'F', 'A'}
    Description of `order`.
```
Когда два или более входных параметра имеют точно такой же тип, форму и описание, их можно объединить:
```
x1, x2 : array_like
    Input arrays, description of `x1`, `x2`.
```
Возвращаемые значения

Описание возвращаемых значений и их типов. Аналогично разделу Параметры, за исключением того, что имя каждого возвращаемого значения необязательно. Тип каждого возвращаемого значения всегда требуется:
```
Returns
-------
int
    Description of anonymous integer return value.
```
Если указаны и имя, и тип, раздел Возвращаемые значения принимает ту же форму, что и раздел Параметры:
```
Returns
-------
err_code : int
    Non-zero value indicates error code, or zero on success.
err_msg : str or None
    Human readable error message, or None on success.
```
Выходные значения

Описание выходных значений и их типов. Это актуально только для генераторов. Аналогично разделу Возвращаемые значения, в том смысле, что имя каждого значения необязательно, но тип каждого значения всегда требуется:
```
Yields
------
int
    Description of the anonymous integer return value.
```
Если указаны и имя, и тип, раздел Выходные значения принимает ту же форму, что и раздел Возвращаемые значения:
```
Yields
------
err_code : int
    Non-zero value indicates error code, or zero on success.
err_msg : str or None
    Human readable error message, or None on success.
```
Поддержка раздела Выходные значения была добавлена в версию numpydoc 0.6.
Принимаемые аргументы

Описание параметров, передаваемых методу генератора .send(), отформатированному как для параметров выше. Поскольку, как и для Выходных значений и Возвращаемых значений, в метод всегда передается один объект, это может описать либо один параметр, либо позиционные аргументы, переданные в виде кортежа. Если в строке документации есть Принимаемые аргументы, она должна также содержать Выходные значения.
Другие параметры

Необязательный раздел, используемый для описания редко используемых параметров. Его следует использовать только в том случае, если функция имеет большое количество ключевых параметров, чтобы избежать загромождения раздела Параметры.
Возбуждаемые исключения

Необязательный раздел, подробно описывающий, какие ошибки могут быть возбуждены и при каких условиях:
```
Raises
------
LinAlgException
    If the matrix is not numerically invertible.
```
Этот раздел следует использовать осмотрительно, т. е. только для ошибок, которые не очевидны или имеют высокую вероятность возбуждения.
Предупреждения

Необязательный раздел, подробно описывающий, какие предупреждения возбуждаются и при каких условиях, отформатированный аналогично разделу Возбуждаемые исключения.

Предупреждения

Необязательный раздел с предостережениями для пользователя в свободном тексте/reST.
См. также

Необязательный раздел, используемый для ссылки на связанный код. Этот раздел может быть очень полезным, но следует использовать его осмотрительно. Цель состоит в том, чтобы направить пользователей к другим функциям, о которых они могут не знать или у которых есть простой способ их обнаружения (например, просматривая строку документации модуля). Функции, чьи строки документации дополнительно объясняют параметры, используемые этой функцией, являются хорошими кандидатами.

Например, для numpy.mean у нас было бы:
```
See Also
--------
average : Weighted average
```
При ссылке на функции в том же подмодуле, префикс не требуется, и дерево ищется вверх для совпадения.

Префиксные функции из других подмодулей должным образом. Например, при документировании модуля random ссылайтесь на функцию в fft следующим образом:
```
fft.fft2 : 2-D fast discrete Fourier transform
```
При ссылке на совершенно другой модуль:
```
scipy.random.norm : Random variates, PDFs, etc.
```
Функции могут быть перечислены без описаний, и это предпочтительно, если функциональность очевидна из имени функции:
```
See Also
--------
func_a : Function a with its description.
func_b, func_c_, func_d
func_e
```
Примечания

Необязательный раздел, который предоставляет дополнительную информацию о коде, возможно, включая обсуждение алгоритма. Этот раздел может включать математические уравнения, написанные в формате LaTeX:
```
The FFT is a fast implementation of the discrete Fourier transform:

.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
```
Уравнения также можно набирать под директивой math:
```
The discrete-time Fourier time-convolution property states that

.. math::

     x(n) * y(n) \Leftrightarrow X(e^{j\omega } )Y(e^{j\omega } )\\
     another equation here
```
Математику можно также использовать встроеным способом, т. е.
```
The value of :math:`\omega` is larger than 5.
```
Имена переменных отображаются в шрифте машинописного текста, полученном с использованием \mathtt{var}:
```
We square the input parameter `alpha` to obtain
:math:`\mathtt{alpha}^2`.
```
Обратите внимание, что LaTeX не очень легко читается, поэтому используйте уравнения экономно.

Изображения разрешены, но не должны быть центральными для объяснения; пользователи, просматривающие строку документации в виде текста, должны иметь возможность понять ее значение без обращения к просмотру изображений. Эти дополнительные иллюстрации включаются с помощью:
```
.. image:: filename
```
где имя_файла — путь, относительный к исходному каталогу руководства.
Ссылки

Ссылки, упомянутые в разделе Примечания, могут быть перечислены здесь, например, если вы процитировали статью ниже, используя текст [1]_, включите её в список следующим образом:
```
.. [1] O. McNoleg, "The integration of GIS, remote sensing,
   expert systems and adaptive co-kriging for environmental habitat
   modelling of the Highland Haggis using object-oriented, fuzzy-logic
   and neural-network techniques," Computers & Geosciences, vol. 22,
   pp. 585-588, 1996.
```
что отображается как 1:

1

O. McNoleg, «Интеграция ГИС, дистанционного зондирования, экспертных систем и адаптивного ко-кригинга для моделирования экологических местообитаний Хайлендского Гагиса с помощью объектно-ориентированных, нечетких логических и нейронных сетей», Computers & Geosciences, т. 22, стр. 585-588, 1996.

Ссылки на временные источники, такие как веб-страницы, не рекомендуются. Ссылки предназначены для дополнения строки документации, но не должны быть необходимыми для понимания её. Ссылки пронумерованы, начиная с единицы, в порядке цитирования.

Предупреждение

Ссылки разрушат таблицы

Там, где ссылки, такие как [1], появляются в таблицах в строке документации numpydoc, разметка таблицы будет нарушена обработкой numpydoc. См. вопрос numpydoc #130

Примеры

Необязательный раздел для примеров, использующий формат doctest. Этот раздел предназначен для иллюстрации использования, а не для предоставления тестовой среды — для этого используйте каталог tests/. Хотя необязательный, этот раздел очень настоятельно рекомендуется.

Когда предоставляется несколько примеров, они должны быть разделены пустыми строками. Комментарии, объясняющие примеры, должны иметь пустые строки как над, так и под ними:
```
>>> np.add(1, 2)
3

Comment explaining the second example

>>> np.add([1, 2], [3, 4])
array([4, 6])
```
Код примера может быть разделен на несколько строк, при этом каждая строка после первой начинается с «… »:
```
>>> np.add([[1, 2], [3, 4]],
...        [[5, 6], [7, 8]])
array([[ 6,  8],
       [10, 12]])
```
Для тестов с результатом, который является случайным или зависит от платформы, отметьте вывод как таковой:
```
>>> import numpy.random
>>> np.random.rand(2)
array([ 0.35773152,  0.38568979])  #random
```
Вы можете запустить примеры как doctests с помощью:
```
>>> np.test(doctests=True)
>>> np.linalg.test(doctests=True)  # for a single module
```
В IPython также можно запустить отдельные примеры, просто скопировав их в режиме doctest:
```
In [1]: %doctest_mode
Exception reporting mode: Plain
Doctest mode is: ON
>>> %paste
 import numpy.random
 np.random.rand(2)
## -- End pasted text --
array([ 0.8519522 ,  0.15492887])
```
Не нужно использовать разметку doctest <BLANKLINE> для обозначения пустых строк в выводе. Обратите внимание, что вариант запуска примеров через numpy.test предоставляется для проверки работы примеров, а не для включения примеров в тестовую среду.

Примеры могут предполагать, что import numpy as np выполняется перед кодом примера в numpy. Дополнительные примеры могут использовать matplotlib для построения графиков, но должны импортировать его явно, например, import matplotlib.pyplot as plt. Все остальные импорты, включая продемонстрированную функцию, должны быть явными.

Когда matplotlib импортируется в примере, код примера будет обернут в директиву matplotlib’s Sphinx `plot <http://matplotlib.org/sampledoc/extensions.html>`_. Когда matplotlib не импортируется явно, plot:: может быть использован напрямую, если matplotlib.sphinxext.plot_directive загружен как расширение Sphinx в conf.py.

Документирование классов

Документация класса

Используйте те же разделы, что и выше (все, кроме Returns применимы). Конструктор (__init__) также должен быть задокументирован здесь, раздел Параметры строки документации описывает параметры конструктора.

Раздел Атрибуты, расположенный ниже раздела Параметры, может быть использован для описания атрибутов класса, не являющихся методами:

Attributes
----------
x : float
    The X coordinate.
y : float
    The Y coordinate.

Атрибуты, которые являются свойствами и имеют свои строки документации, могут быть просто перечислены по имени:

Attributes
----------
real
imag
x : float
    The X coordinate
y : float
    The Y coordinate

В целом, нет необходимости перечислять методы класса. Те, которые не являются частью публичного API, имеют имена, начинающиеся с подчеркивания. Однако в некоторых случаях у класса может быть очень много методов, из которых лишь немногие являются релевантными (например, подклассы ndarray). Тогда становится полезным иметь дополнительный раздел Методы:

class Photo(ndarray):
    """
    Array with associated photographic information.

    ...

    Attributes
    ----------
    exposure : float
        Exposure in seconds.

    Methods
    -------
    colorspace(c='rgb')
        Represent the photo in the given colorspace.
    gamma(n=1.0)
        Change the photo's gamma exposure.

    """

Если необходимо объяснить частный метод (используйте с осторожностью!), на него можно сослаться в разделе Подробное описание или Примечания. Не указывайте частные методы в разделе методы.

Обратите внимание, что self не указывается как первый параметр методов.

Документация методов

Документируйте их так же, как и любые другие функции. Не включайте self в список параметров. Если метод имеет эквивалентную функцию (что часто бывает, например, для методов ndarray), строка документации функции должна содержать подробное описание, а строка документации метода должна ссылаться на неё. В строке документации метода должны быть только краткое описание и раздел См. также. Метод должен использовать раздел Возвращает или Выдаёт, в зависимости от ситуации.

Документирование экземпляров классов

Экземпляры классов, которые являются частью API NumPy (например, np.r_ np,c_, np.index_exp, и т. д.), могут потребовать некоторой осторожности. Для того, чтобы дать этим экземплярам полезную строку документации, мы делаем следующее:

Единственный экземпляр: Если представлен только один экземпляр класса, необходимо задокументировать класс. Примеры могут использовать имя экземпляра.
Несколько экземпляров: Если представлены несколько экземпляров, строки документации для каждого экземпляра записываются и присваиваются атрибутам экземпляров __doc__ во время выполнения. Класс документируется как обычно, а представленные экземпляры могут быть упомянуты в разделах Примечания и См. также.

Документирование генераторов

Генераторы должны быть задокументированы так же, как и функции. Единственное различие заключается в том, что следует использовать раздел Выдаёт вместо раздела Возвращает. Поддержка раздела Выдаёт была добавлена в версию numpydoc 0.6.

Документирование констант

Используйте те же разделы, что и для функций, где это применимо:

1. summary
2. extended summary (optional)
3. see also (optional)
4. references (optional)
5. examples (optional)

Строки документации для констант не будут видны в текстовых терминалах (константы имеют неизменяемый тип, поэтому строки документации нельзя назначить им, как для экземпляров класса), но будут отображаться в документации, созданной с помощью Sphinx.

Документирование модулей

Каждый модуль должен иметь строку документации с, по меньшей мере, строкой резюме. Другие разделы являются необязательными и должны использоваться в том же порядке, что и при документировании функций, когда они уместны:

1. summary
2. extended summary
3. routine listings
4. see also
5. notes
6. references
7. examples

Рекомендуется создание списков процедур, особенно для больших модулей, для которых трудно получить общее представление обо всех предоставляемых функциях, просматривая исходные файлы или словарь __all__.

Обратите внимание, что информация о лицензии и авторах, хотя часто включается в исходные файлы, не должна содержаться в строках документации.

Другие моменты, которые следует учитывать

Уравнения: как обсуждалось в разделе Примечания выше, форматирование LaTeX следует свести к минимуму. Часто можно показать уравнения в виде кода Python или псевдокода вместо этого, что гораздо лучше читается в терминале. Для вывода в строку используйте двойные обратные кавычки (например, y = np.sin(x)). Для вывода с пустыми строками сверху и снизу используйте двойные двоеточия и отступьте код, как:
```
end of previous sentence::

    y = np.sin(x)
```
Примечания и Предупреждения: Если в строке документации есть моменты, которые заслуживают особого внимания, можно использовать директивы reST для примечания или предупреждения рядом с контекстом предупреждения (внутри раздела). Синтаксис:
```
.. warning:: Warning text.

.. note:: Note text.
```
Используйте их экономно, так как они не очень хорошо выглядят в текстовых терминалах и не всегда необходимы. Один случай, когда предупреждение может быть полезным, — это маркировка известной ошибки, которая ещё не исправлена.
array_like: Для функций, принимающих аргументы, которые могут иметь не только тип ndarray, но также типы, которые могут быть преобразованы в массив ndarray (например, скалярные типы, последовательности), эти аргументы могут быть задокументированы с типом array_like.
Ссылки: Если вам нужно включить гиперссылки в строку документации, имейте в виду, что некоторые разделы строк документации не обрабатываются как стандартные reST, и в этих разделах numpydoc может сбиться с толку целевыми гиперссылками, такими как:
```
.. _Example: http://www.example.com
```
Если сборка Sphinx выводит предупреждение вида WARNING: Unknown target name: "example", значит, это происходит. Чтобы избежать этой проблемы, используйте форму гиперссылки в строке:
```
`Example <http://www.example.com>`_
```

Общие понятия reST

Для абзацев отступы важны и указывают на отступы в выводе. Новые абзацы обозначаются пустой строкой.

Используйте *italics*, **bold** и ``monospace`` при необходимости в любых объяснениях (но не для имён переменных и кода doctest или многострочного кода). Имена переменных, модулей, функций и классов должны быть написаны в одинарных обратных кавычках (`numpy`).

Более подробный пример разметки reST можно найти в этом примере документа; быстрый справочник полезен при редактировании.

Интервалы строк и отступы важны и должны тщательно соблюдаться.

Заключение

Этот документ сам написан в формате ReStructuredText. Пример представленного здесь формата доступен.

Пример исходного кода

"""This is the docstring for the example.py module.  Modules names should
have short, all-lowercase names.  The module name may have underscores if
this improves readability.

Every module should have a docstring at the very top of the file.  The
module's docstring may extend over multiple lines.  If your docstring does
extend over multiple lines, the closing three quotation marks must be on
a line by itself, preferably preceded by a blank line.

"""
from __future__ import division, absolute_import, print_function

import os  # standard library imports first

# Do NOT import using *, e.g. from numpy import *
#
# Import the module using
#
#   import numpy
#
# instead or import individual functions as needed, e.g
#
#  from numpy import array, zeros
#
# If you prefer the use of abbreviated module names, we suggest the
# convention used by NumPy itself::

import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt

# These abbreviated names are not to be used in docstrings; users must
# be able to paste and execute docstrings after importing only the
# numpy module itself, unabbreviated.


def foo(var1, var2, long_var_name='hi'):
    r"""A one-line summary that does not use variable names or the
    function name.

    Several sentences providing an extended description. Refer to
    variables using back-ticks, e.g. `var`.

    Parameters
    ----------
    var1 : array_like
        Array_like means all those objects -- lists, nested lists, etc. --
        that can be converted to an array.  We can also refer to
        variables like `var1`.
    var2 : int
        The type above can either refer to an actual Python type
        (e.g. ``int``), or describe the type of the variable in more
        detail, e.g. ``(N,) ndarray`` or ``array_like``.
    long_var_name : {'hi', 'ho'}, optional
        Choices in brackets, default first when optional.

    Returns
    -------
    type
        Explanation of anonymous return value of type ``type``.
    describe : type
        Explanation of return value named `describe`.
    out : type
        Explanation of `out`.
    type_without_description

    Other Parameters
    ----------------
    only_seldom_used_keywords : type
        Explanation
    common_parameters_listed_above : type
        Explanation

    Raises
    ------
    BadException
        Because you shouldn't have done that.

    See Also
    --------
    otherfunc : relationship (optional)
    newfunc : Relationship (optional), which could be fairly long, in which
              case the line wraps here.
    thirdfunc, fourthfunc, fifthfunc

    Notes
    -----
    Notes about the implementation algorithm (if needed).

    This can have multiple paragraphs.

    You may include some math:

    .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}

    And even use a Greek symbol like :math:`\omega` inline.

    References
    ----------
    Cite the relevant literature, e.g. [1]_.  You may also cite these
    references in the notes section above.

    .. [1] O. McNoleg, "The integration of GIS, remote sensing,
       expert systems and adaptive co-kriging for environmental habitat
       modelling of the Highland Haggis using object-oriented, fuzzy-logic
       and neural-network techniques," Computers & Geosciences, vol. 22,
       pp. 585-588, 1996.

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a = [1, 2, 3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    >>> print "a\n\nb"
    a
    b

    """

    pass

Пример рендеринга

Это строка документации для модуля example.py. Имена модулей должны иметь короткие имена в нижнем регистре. В имени модуля могут быть подчеркивания, если это улучшает читаемость.

Каждый модуль должен иметь строку документации в самом верху файла. Строка документации модуля может занимать несколько строк. Если ваша строка документации занимает несколько строк, закрывающие три кавычки должны быть на отдельной строке, предпочтительно перед пустой строкой.

doc.example.foo(var1, var2, long_var_name='hi') [source]

Однострочное резюме, которое не использует имена переменных или имя функции.

Несколько предложений, предоставляющих расширенное описание. Ссылайтесь на переменные, используя обратные кавычки, например var.

Параметры

var1array_like: Array_like означает все эти объекты — списки, вложенные списки и т. д. — которые могут быть преобразованы в массив. Мы также можем ссылаться на переменные, такие как var1.
var2int: Указанный выше тип может ссылаться на фактический тип Python (например, int), или описывать тип переменной более подробно, например, (N,) ndarray или array_like.
long_var_name{‘hi’, ‘ho’}, optional: Варианты в скобках, по умолчанию первый при опциональности.

Возвращает

тип: Описание анонимного возвращаемого значения типа type.
describetype: Описание возвращаемого значения с именем describe.
outtype: Описание out.
тип_без_описания

Другие параметры

only_seldom_used_keywordstype: Объяснение
common_parameters_listed_abovetype: Объяснение

Возбуждает

BadException: Потому что вы этого не должны были делать.

См. также

otherfunc: отношение (необязательно)
newfunc: Отношение (необязательно), которое может быть достаточно длинным, в этом случае строка переносится сюда.

thirdfunc, fourthfunc, fifthfunc

Примечания

Примечания об алгоритме реализации (при необходимости).

Это может содержать несколько абзацев.

Вы можете включить некоторые математические обозначения:

$X(e^{j\omega } ) = x(n)e^{ - j\omega n}$

И даже использовать греческую букву, например, $\omega$ в строке.

Ссылки

Ссылка на соответствующую литературу, например, [1]. Вы также можете ссылаться на эти ссылки в разделе «Примечания» выше.

1: O. McNoleg, «Интеграция ГИС, дистанционного зондирования, экспертных систем и адаптивного ко-кригинга для моделирования экологической среды высокогорных хаггис с использованием объектно-ориентированных, нечетких логических и нейронных сетей», Computers & Geosciences, том 22, стр. 585-588, 1996.

Примеры

Они написаны в формате doctest и должны иллюстрировать, как использовать функцию.

>>> a = [1, 2, 3]
>>> print [x + 3 for x in a]
[4, 5, 6]
>>> print "a\n\nb"
a
b

© 2005–2020 NumPy Developers
Licensed under the 3-clause BSD License.
https://numpy.org/doc/1.18/docs/howto_document.html