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

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

• В целом, мы следуем руководству по стилю документации Google для разработчиков.

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

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

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

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

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

При использовании 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 здесь, как показано в их примере