Вклад в документацию#

Вклад в документацию приносит пользу всем, кто использует pandas. Мы призываем вас помочь нам улучшить документацию, и вам не нужно быть экспертом по pandas для этого! На самом деле, существуют разделы документации, которые стали хуже после написания их экспертами. Если что-то в документации вам непонятно, обновление соответствующего раздела после того, как вы разберетесь, — отличный способ убедиться, что это поможет следующему человеку. Пожалуйста, посетите страница проблем для полного списка проблем, которые в настоящее время открыты в документации Pandas.

О документации pandas #

Документация написана на reStructuredText, что почти как написание на простом английском языке, и построено с использованием SphinxВ документации Sphinx есть отличный введение в reST. Ознакомьтесь с документацией Sphinx для выполнения более сложных изменений в документации.

Некоторые другие важные вещи, которые нужно знать о документации:

Документация pandas состоит из двух частей: строк документации в самом коде и документации в этой папке doc/.

Строки документации предоставляют четкое объяснение использования отдельных функций, в то время как документация в этой папке состоит из обучающих обзоров по темам вместе с другой информацией (что нового, установка и т.д.).
Строки документации следуют соглашению pandas, основанному на Стандарт Numpy Docstring. Следуйте руководство по документации pandas для подробных инструкций о том, как написать правильную строку документации.
- руководство по документации pandas
В учебных пособиях активно используется Директива IPython расширение sphinx. Эта директива позволяет помещать код в документацию, который будет выполняться во время сборки документации. Например:
```
.. ipython:: python

    x = 2
    x**3
```
будет отображено как:
```
In [1]: x = 2

In [2]: x**3
Out[2]: 8
```
Почти все примеры кода в документации выполняются (и их вывод сохраняется) во время сборки документации. Этот подход гарантирует, что примеры кода всегда будут актуальными, но делает сборку документации немного сложнее.
Наши файлы документации API в doc/source/reference размещает автоматически сгенерированную документацию из строк документации. Для классов есть несколько тонкостей в управлении тем, какие методы и атрибуты имеют автоматически сгенерированные страницы.

У нас есть два шаблона автоподведения итогов для классов.
1. _templates/autosummary/class.rstИспользуйте это, когда хотите автоматически создать страницу для каждого публичного метода и атрибута класса. Attributes и Methods разделы будут автоматически добавлены в отображаемую документацию класса с помощью numpydoc. См. DataFrame для примера.
2. _templates/autosummary/class_without_autosummary. Используйте это, когда хотите выбрать подмножество методов/атрибутов для автоматической генерации страниц. При использовании этого шаблона следует включить Attributes и Methods раздел в строке документации класса. См. CategoricalIndex для примера.
Каждый метод должен быть включен в toctree в одном из файлов документации в doc/source/reference, иначе Sphinx выдаст предупреждение.

Утилитарный скрипт scripts/validate_docstrings.py можно использовать для получения csv-сводки документации API. А также для проверки распространенных ошибок в docstring конкретного класса, функции или метода. Сводка также сравнивает список методов, задокументированных в файлах в doc/source/reference (который используется для генерации Справочник API странице) и фактическими публичными методами. Это позволит идентифицировать методы, задокументированные в doc/source/reference которые на самом деле не являются методами класса, и существующие методы, которые не задокументированы в doc/source/reference.

Обновление строки документации pandas #

При улучшении документации отдельной функции или метода не обязательно собирать полную документацию (см. следующий раздел). Однако существует скрипт, проверяющий документацию (например, для DataFrame.mean метод):

python scripts/validate_docstrings.py pandas.DataFrame.mean

Этот скрипт укажет на некоторые ошибки форматирования, если они присутствуют, а также запустит и протестирует примеры, включенные в строку документации. Проверьте руководство по документации pandas для подробного руководства по форматированию строки документации.

Примеры в docstring ('doctests') должны быть валидным кодом Python, который детерминированно возвращает представленный вывод и может быть скопирован и запущен пользователями. Это можно проверить с помощью скрипта выше, а также тестируется на Travis. Неудачный doctest будет блокировать слияние PR. Проверьте примеры раздел в руководстве по документации для некоторых советов и трюков, чтобы пройти доктесты.

При выполнении PR с обновлением строки документации, рекомендуется опубликовать вывод скрипта валидации в комментарии на github.

Как собрать документацию pandas #

Требования #

Сначала вам необходимо иметь среду разработки, чтобы иметь возможность собрать pandas (см. документацию по создание среды разработки).

Сборка документации #

Итак, как собрать документацию? Перейдите в локальный doc/ каталог в консоли и запустите:

python make.py html

Затем вы можете найти HTML-вывод в папке doc/build/html/.

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

Если вы хотите выполнить полную чистую сборку, сделайте:

python make.py clean
python make.py html

Вы можете сказать make.py скомпилировать только один раздел документации, значительно сокращая время проверки ваших изменений.

# omit autosummary and API section
python make.py clean
python make.py --no-api

# compile the docs with only a single section, relative to the "source" folder.
# For example, compiling only this guide (doc/source/development/contributing.rst)
python make.py clean
python make.py --single development/contributing.rst

# compile the reference docs for a single function
python make.py clean
python make.py --single pandas.DataFrame.join

# compile whatsnew and API section (to resolve links in the whatsnew)
python make.py clean
python make.py --whatsnew

Для сравнения, полная сборка документации может занять 15 минут, но отдельный раздел может занять 15 секунд. Последующие сборки, которые обрабатывают только измененные части, будут быстрее.

Сборка автоматически использует количество ядер, доступных на вашем компьютере, чтобы ускорить построение документации. Вы можете переопределить это:

python make.py html --num-jobs 4

Откройте следующий файл в веб-браузере, чтобы увидеть полную документацию, которую вы только что собрали doc/build/html/index.html.

И вы получите удовлетворение от просмотра вашей новой и улучшенной документации!

Сборка документации основной ветки #

Когда pull request'ы объединяются в pandas main ветке, основные части документации также собираются Travis-CI. Эти документы затем размещаются здесь, см. также Непрерывная интеграция раздел.

Предварительный просмотр изменений #

После отправки pull request, GitHub Actions автоматически соберёт документацию. Чтобы просмотреть собранный сайт:

Ожидание CI / Web and docs проверка для завершения.
Нажмите Details рядом с ним.
Из Artifacts выпадающий список, клик docs или website чтобы скачать сайт в виде ZIP-файла.

Вклад в документацию#

О документации pandas#

Обновление строки документации pandas#

Как собрать документацию pandas#

Требования#

Сборка документации#

Сборка документации основной ветки#

Предварительный просмотр изменений#