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

В настоящее время для генерации 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

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

cd doc
make html

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

Если вы создали numpy в виртуальной среде и получите ошибку, которая гласит numpy not found, cannot build documentation without..., вам необходимо переопределить переменную makefile PYTHON в командной строке, поэтому вместо написания make  html напишите:

make PYTHON=python html

Обратите внимание, что создание документации в 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.