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

Документация для пользователей

• В целом, мы следуем руководству по стилю документации разработчиков Google https://developers.google.com/style.

• Стиль NumPy применяется в следующих случаях:

  • Когда у Google нет рекомендаций, или
  • Когда мы предпочитаем не использовать стиль Google

  Наши текущие правила:

  • Мы склоняем слово index к множественному числу как indices, а не indexes, следуя примеру numpy.indices.
  • Для согласованности мы также склоняем matrix к множественному числу как matrices.
• Вопросы грамматики, недостаточно подробно рассмотренные правилами NumPy или Google, решаются в разделе «Грамматика и использование» в последнем издании Справочника Чикагского стиля.
• Мы приветствуем сообщения о случаях, которые следует добавить в правила стиля NumPy https://github.com/numpy/numpy/issues.

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

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

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

Он доступен по следующим адресам:

• numpydoc на PyPI
• numpydoc на GitHub

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

import numpy.fft

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

np.fft.fft2(...)

Пожалуйста, используйте стандарт форматирования numpydoc https://numpydoc.readthedocs.io/en/latest/format.html, как показано в их примере