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

Мы стремимся узнавать и исправлять дефекты документации. Но чтобы решать самые большие проблемы, нам приходится откладывать или игнорировать некоторые отчеты об ошибках. Вот лучшие дефекты, за которые стоит взяться.

Высший приоритет отдается технические неточности – отсутствующий в docstring параметр, некорректное описание функции/параметра/метода и т.д. Также приоритет имеют другие «структурные» дефекты, такие как неработающие ссылки. Все эти исправления легко проверить и внедрить. Вы можете отправить pull request (PR) с исправлением, если вы знаете, как это сделать; в противном случае, пожалуйста, открыть проблему.

Опечатки и орфографические ошибки попадают на нижнюю ступень; мы рады услышать о них, но можем не иметь возможности быстро их исправить. Их также можно обработать как pull-запросы или issues.

Очевидно формулировка ошибки (например, пропуск «не») попадают в категорию опечаток, но другие переформулировки — даже для грамматики — требуют субъективной оценки, что повышает планку. Можно представить случаи, когда неясно, следует ли вносить «исправление», например:

  • Попытка 'исправить' все случаи использования (или их отсутствие) оксфордской запятой.

  • Случаи, когда правильность общепринятого использования развивается, например, "состоящий из"

Самые простые исправления для принятия — те, где исходная версия явно и недвусмысленно ошибочна; изменения, требующие тонкого редакторского суждения, вероятно, лучше избегать. (Но обратите внимание, что это не касается обновления документации для исправления запутанных утверждений или решения других проблем документации, о которых сообщают пользователи.)

Примечание

В качестве общего руководства старайтесь накапливать небольшие изменения в документации (например, опечатки) вместо того, чтобы отправлять их по одному. По возможности также убедитесь, что используете правильные команды для пропустить проверки CI на изменениях в документации.

Некоторые функции/объекты, определенные в модулях расширений C или Fortran, имеют свои строки документации, определенные отдельно от фактического кода. Убедитесь, что выполнили поиск строки документации для нужной функции, используя либо grep или других подобных инструментов.

Локальная сборка документации с помощью Sphinx#

Docstrings SciPy преобразуются в HTML с помощью Sphinx и Тема PyData Sphinx. Написание docstrings описано в Стиль документации; этот документ объясняет, как проверить, что строки документации отображаются правильно.

Для видеообзора см. Рендеринг документации SciPy с помощью Sphinx .

Чтобы отобразить документацию на своём компьютере:

  1. Убедитесь, что у вас есть рабочая сборка SciPy (см. Сборка из исходного кода).

  2. Затем запустите python dev.py doc для сборки документации. Это может занять некоторое время при первом запуске, но последующие сборки документации обычно выполняются значительно быстрее.

  3. Просмотрите документацию в doc/build/html/. Вы можете начать с index.html и просматривать, или вы можете перейти прямо к файлу, который вас интересует.

Примечание

  • Изменения в определённых документах не вступают в силу при пересборке документации Sphinx. В этом случае можно собрать с нуля, удалив каталоги scipy/doc/build и source/reference/generated, или запустив python dev.py doc clean затем снова собрать документацию.

  • Если версия SciPy, найденная с помощью вышеуказанной команды, отличается от версии последнего коммита в репозитории, вы увидите сообщение вида:

    installed scipy 5fd20ec1aa != current repo git version '35fd20ec1a'

    Это указывает на то, что вы, вероятно, используете неправильную установку SciPy, проверьте с помощью python -c "import scipy; print(scipy.__file__)".

  • Документация SciPy содержит интерактивные примеры, отображаемые с помощью jupyterlite-sphinx расширение. Для получения дополнительных сведений см. Добавление или редактирование учебников в виде Jupyter notebooks и Интерактивные примеры в строках документации.

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

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

  1. Войти в GitHub.

  2. Войти CircleCI используя ваш аккаунт GitHub.

  3. Вернувшись в GitHub, внизу PR выберите «Show all Checks».

  4. Рядом с "Check the rendered docs here!", выберите "Details".

Руководство по документации#

Используйте "должен", а не "следует"#

При указании обязательного условия для входных параметров слово 'must' предпочтительнее, чем 'should'. Для многих носителей английского языка 'must' подразумевает более строгое ограничение, чем 'should', например, 'I must have oxygen to live' против 'I should exercise more'.

Да:

Parameters
----------
x : float
    `x` must be nonnegative.

Нет:

Parameters
----------
x : float
    `x` should be nonnegative.

Использование разметки 'versionadded'#

  • Для новой функции разметка 'versionadded' помещается в раздел «Примечания», не в описании в начале строки документации.

  • Для нового аргумента, добавленного к существующей функции, разметка 'versionadded' размещается в конце описания аргумента в разделе "Параметры".

Цитирование статей Википедии в разделе «Ссылки»#

Допустимо использовать статьи Википедии в качестве ссылок. При создании цитирования для ссылки укажите заголовок статьи, название “Wikipedia” (аналогично тому, как указывается название журнала) и URL.

Да:

.. [1] "Zeta Distribution", Wikipedia,
       https://en.wikipedia.org/wiki/Zeta_distribution

Нет:

.. [1] https://en.wikipedia.org/wiki/Zeta_distribution

DOI в ссылках#

Использование DOI в ссылках настоятельно рекомендуется. В Sphinx есть специальный синтаксис для DOI: :doi:. Например:

.. [2] D. Fishkind, S. Adali, H. Patsolic, L. Meng, D. Singh, V. Lyzinski,
       C. Priebe, "Seeded graph matching", Pattern Recognit. 87 (2019):
       203-215, :doi:`10.1016/j.patcog.2018.09.014`

(статьи arXiv также имеют специальную разметку: :arxiv:.)

Маркированные списки#

Это не столько руководство, сколько напоминание о разметке Sphinx для маркированных списков. Неправильное использование отступов встречается достаточно часто, чтобы упомянуть об этом здесь.

При создании маркированного списка:

  • Не заканчивайте предыдущую строку ::.

  • Не делайте отступы для маркеров списка.

  • Добавьте пустую строку до и после списка.

Некоторые примеры:

Да:

Some text that precedes this interesting list:

* The first item in the list.
* The second item in the list.
* You get the idea.

Some text that follows the list.

Нет:

Some text that precedes this interesting list:

  * The first item in the list.
  * The second item in the list.
  * You get the idea.

Some text that follows the list.

Нет:

Some text that precedes this interesting list:
* The first item in the list.
* The second item in the list.
* You get the idea.
Some text that follows the list.

Автономные примеры#

Каждый раздел «Пример» (как в строках документации, так и в общей документации) должен быть самодостаточным. Это означает, что все импорты должны быть явными, используемые данные должны быть определены, и код должен «просто работать» при копировании-вставке в свежий интерпретатор Python.

Да:

>>> import numpy as np
>>> rng = np.random.default_rng()

Нет:

>>> rng = np.random.default_rng()

Что возможно (и рекомендуется) - чередовать блоки кода с объяснениями. Пустые строки должны отделять каждый блок кода от пояснительного текста.

Да:

Some initial text

>>> import numpy as np
>>> rng = np.random.default_rng()

This is some explanation

>>> rng.random(10)

Примеры и случайность#

В наборе непрерывной интеграции (CI) примеры выполняются, и их вывод сравнивается с предоставленным эталоном. Основная цель — убедиться, что пример корректен; неудача предупреждает нас, что пример может потребовать корректировки (например, потому что API изменился с момента его написания). Doctests не предназначены для использования в качестве модульных тестов базовой реализации.

В случае, если требуется генератор случайных чисел, np.random.Generator должен быть использован. Канонический способ создания NumPy Generator используйте np.random.default_rng.

Да:

>>> import numpy as np
>>> rng = np.random.default_rng()
>>> sample = rng.random(10)

Да:

>>> import numpy as np
>>> rng = np.random.default_rng(102524723947864966825913730119128190984)
>>> sample = rng.random(10)

Нет:

>>> import numpy as np
>>> sample = np.random.random(10)

Инициализация генератора необязательна. Если используется seed, избегайте общих чисел и вместо этого сгенерируйте seed с помощью np.random.SeedSequence().entropy. Если начальное значение не задано, используется значение по умолчанию 1638083107694713882823079058616272161 используется при выполнении doctests. В любом случае, отображаемая documentation не будет показывать seed. Цель — отговорить пользователей от копирования/вставки seeds в их код и вместо этого принять явное решение об использовании seed в их программе. Следствием является то, что пользователи не могут точно воспроизвести результаты примера, поэтому примеры, использующие случайные данные, не должны ссылаться на точные числовые значения, основанные на случайных данных, или полагаться на них для доказательства своей точки.

Директива наследия#

Если функция, модуль или API находится в устаревший режим, означающий, что он сохраняется по причинам обратной совместимости, но не рекомендуется для использования в новом коде. Вы можете использовать .. legacy:: директива.

По умолчанию, если используется без аргументов, директива legacy сгенерирует следующий вывод:

Наследие

Этот подмодуль считается устаревшим и больше не будет получать обновления. Хотя у нас в настоящее время нет планов по его удалению, мы рекомендуем использовать более современные альтернативы для нового кода.

Настоятельно рекомендуем также добавить пользовательское сообщение, например, о новом API для замены старого. Это сообщение будет добавлено к стандартному сообщению:

.. legacy::

   New code should use :mod:`scipy.fft`.

создаст следующий вывод:

Наследие

Этот подмодуль считается устаревшим и больше не будет получать обновления. Хотя у нас в настоящее время нет планов по его удалению, мы рекомендуем, чтобы новый код использовал более современные альтернативы. Новый код должен использовать scipy.fft.

Наконец, если вы хотите упомянуть функцию, метод (или любой пользовательский объект) вместо подмодуль, вы можете использовать необязательный аргумент:

.. legacy:: function

Это создаст следующий вывод:

Наследие

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

—