Создание документации NumPy API и справочных материалов

В настоящее время для генерации API и справочной документации NumPy используется Sphinx. Вам потребуется Sphinx 1.8.3 <= 1.8.5.

Если вам нужен только документ, обратите внимание, что предварительно скомпилированные версии доступны по адресу

https://docs.scipy.org/

в нескольких форматах.

Инструкции

Если вы получили NumPy через git, получите также подмодули git, содержащие дополнительные части, необходимые для создания документации:

git submodule init
git submodule update

Кроме того, для создания документации требуется расширение Sphinx plot_directive, которое поставляется с Matplotlib. Это расширение Sphinx можно установить, установив Matplotlib. Вам также потребуется python3.6.

Поскольку большая часть основной документации получена из NumPy с помощью import numpy и анализа строк документации, вам сначала необходимо создать NumPy и установить его, чтобы была импортирована правильная версия.

Обратите внимание, что вы можете, например, установить NumPy в временную папку и соответствующим образом установить переменную среды PYTHONPATH.

После установки NumPy установите SciPy, так как для корректного отображения некоторых графиков в модуле random требуется scipy.special. Теперь вы готовы сгенерировать документацию, поэтому напишите:

make html

в каталоге doc/. При успешном выполнении это сгенерирует подкаталог build/html, содержащий сгенерированную документацию. Если вы получите сообщение об installed numpy != current repo git version, вы должны либо переопределить проверку, установив GITVER, либо переустановить NumPy.

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

Для создания документации в формате PDF выполните:

make latex
make -C build/latex all-pdf

Для этого вам понадобится установленный LaTeX.

Вместо вышеперечисленного вы также можете выполнить:

make dist

что пересоздаст NumPy, установит его во временную папку и создаст документацию во всех форматах. Скорее всего, это будет работать только на платформах Unix.

Документация NumPy, размещенная на https://docs.scipy.org в формате html и pdf, также создается с помощью make dist. Подробные сведения о том, как обновить https://docs.scipy.org, см. в файле HOWTO RELEASE.

Расширения Sphinx

Документация NumPy использует несколько пользовательских расширений Sphinx. Они находятся в каталоге sphinxext/ (в качестве подмодулей git, как описано выше) и автоматически включаются при создании документации NumPy.

Если вы хотите использовать эти расширения в сторонних проектах, они доступны на PyPi как пакет numpydoc.