Создание документации 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 и анализа строк документации, вам сначала необходимо построить 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. Подробности об обновлении https://numpy.org/doc см. в HOWTO RELEASE.

Расширения Sphinx

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

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