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

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

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

Среды разработки#

Прежде чем продолжить, следует отметить, что документация строится с помощью make инструмент, который изначально недоступен в Windows. Пользователи MacOS или Linux могут перейти к Предварительные требования. Для пользователей Windows рекомендуется настроить среду разработки в GitHub Codespaces (см. Рекомендуемая настройка разработки) или Подсистема Windows для Linux (WSL). WSL — хороший вариант для постоянной локальной настройки.

Предварительные требования#

Сборка документации NumPy и справочника API требует следующего:

NumPy#

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

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

Зависимости#

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

pip install -r requirements/doc_requirements.txt

Примечание

Может потребоваться установить версии для разработки зависимостей документации, чтобы собрать документацию локально:

pip install --pre --force-reinstall --extra-index-url \
https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \
-r requirements/doc_requirements.txt

В настоящее время мы используем Sphinx вместе с Doxygen для генерации API и справочной документации для NumPy. Кроме того, сборка документации требует расширения Sphinx plot_directive, который поставляется с Matplotlib. Мы также используем numpydoc для отображения строк документации в сгенерированной документации API. SciPy установлен, так как некоторые части документации требуют функций SciPy.

Для установки Doxygen, пожалуйста, проверьте официальный скачать и установка страниц, или если вы используете Linux, то можете установить его через менеджер пакетов вашего дистрибутива.

Примечание

Попробуйте установить более новую версию Doxygen > 1.8.10, иначе вы можете получить некоторые предупреждения во время сборки.

Подмодули#

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

git submodule update --init

Инструкции#

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

spin docs

Это соберет NumPy из исходного кода, если вы еще этого не сделали, и запустит Sphinx для сборки html документации. Если всё пройдёт хорошо, это сгенерирует build/html подкаталог в /doc каталог, содержащий собранную документацию.

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