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

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

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

https://numpy.org/doc/

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

Инструкции

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

git submodule update --init

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

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

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

Обратите внимание, что вы можете, например, установить NumPy во временную папку и соответствующим образом установить переменную окружения PYTHONPATH. В качестве альтернативы, если вы используете виртуальные среды Python (например, conda, virtualenv или модуль venv), рекомендуется установить numpy в новую виртуальную среду. Все необходимые зависимости для построения документации NumPy можно установить с помощью:

pip install -r doc_requirements.txt

Теперь вы готовы сгенерировать документацию, поэтому напишите:

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, включая поддержку греческих букв. Например, в Ubuntu xenial необходимо установить texlive-lang-greek и cm-super. Также latexmk необходимо на системах, отличных от Windows.

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

make dist

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

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

Расширения Sphinx

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

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