Как внести вклад в документацию NumPy#
Это руководство поможет вам решить, что внести и как отправить это в официальную документацию NumPy.
Встречи команды документации#
Сообщество NumPy поставило твёрдую цель улучшить свою документацию. Мы проводим регулярные встречи по документации на Zoom (даты объявляются на список рассылки numpy-discussion), и все приветствуются. Обращайтесь, если у вас есть вопросы или вам нужен кто-то, кто проведёт вас через первые шаги – мы рады помочь. Протоколы ведутся на hackmd.io и хранится в Репозиторий архива NumPy.
Что нужно#
The Документация NumPy содержит подробную информацию. Справочная документация по API генерируется непосредственно из строки документации в коде, когда документация встроенный. Хотя у нас в основном полная справочная документация для каждой функции и класса, доступных пользователям, не хватает примеров использования для некоторых из них.
Нам не хватает документации с более широким охватом — руководств, инструкций и объяснений. Сообщение об ошибках — еще один способ внести вклад. Мы обсуждаем оба.
Внесение исправлений#
Мы стремимся узнавать и исправлять дефекты документации. Но чтобы решать самые большие проблемы, нам приходится откладывать или игнорировать некоторые отчеты об ошибках. Вот лучшие дефекты, за которые стоит взяться.
Высший приоритет отдается технические неточности – отсутствие параметра в docstring, неверное описание функции/параметра/метода и т.д. Другие «структурные» дефекты, такие как сломанные ссылки, также имеют приоритет. Все эти исправления легко подтвердить и внедрить. Вы можете отправить запрос на включение (PR) с исправлением, если вы знаете, как это сделать; в противном случае, пожалуйста, открыть проблему.
Опечатки и орфографические ошибки попадают на нижнюю ступень; мы рады услышать о них, но можем не иметь возможности быстро их исправить. Их также можно обработать как pull-запросы или issues.
Очевидно формулировка ошибки (например, пропуск "не") попадают в категорию опечаток, но другие переформулировки – даже для грамматики – требуют субъективной оценки, что повышает планку. Проверьте почву, сначала представив исправление как issue.
Некоторые функции/объекты, такие как numpy.ndarray.transpose, numpy.array и т.д., определенные в модулях C-расширений, имеют свои строки документации, определенные отдельно в _add_newdocs.py
Добавление новых страниц#
Ваши трудности при использовании нашей документации — наш лучший ориентир для исправлений.
Если вы напишете недостающую документацию, вы присоединитесь к передовой линии open source, но это значимый вклад просто сообщить нам, чего не хватает. Если вы хотите составить документ, обсудите свои мысли с список рассылки для дальнейших идей и обратной связи. Если вы хотите сообщить нам о пробеле, открыть проблему. См. этой проблемы для примера.
Если вы ищете темы, наш формальный план документации — это Предложение по улучшению NumPy (NEP), NEP 44 — Реструктуризация документации NumPy. Он определяет области, где наша документация нуждается в помощи, и перечисляет несколько дополнений, которые мы хотели бы видеть, включая Jupyter notebooks.
Фреймворк документации#
Существуют формулы для написания полезных документов, и четыре формулы
охватывают почти всё. Есть четыре формулы, потому что есть четыре
категории документов – tutorial, how-to guide, explanation,
и reference. Идея о том, что документация делится таким образом, принадлежит Даниэле Прожиде и его Diátaxis Framework. Когда вы начинаете документ или предлагаете его, имейте в виду, к какому из этих типов он будет относиться.
Учебники по NumPy#
В дополнение к документации, которая является частью исходного кода NumPy, вы можете отправлять контент в формате Jupyter Notebook в Учебники по NumPy странице. Этот набор учебных и образовательных материалов предназначен для предоставления высококачественных ресурсов проектом NumPy, как для самостоятельного обучения, так и для преподавания на занятиях. Эти ресурсы разрабатываются в отдельном репозитории GitHub, numpy-tutorials, где вы можете просмотреть существующие блокноты, открыть issues, чтобы предложить новые темы, или отправить свои собственные учебники как pull requests.
Подробнее о вкладе#
Не беспокойтесь, если английский не ваш родной язык или если вы можете предложить только черновик. Открытый исходный код — это совместные усилия сообщества. Сделайте всё возможное — мы поможем исправить проблемы.
Изображения и реальные данные делают текст более увлекательным и мощным, но убедитесь, что используемое вами имеет соответствующую лицензию и доступно. Здесь снова даже грубая идея для иллюстрации может быть доработана другими.
На данный момент единственные форматы данных, принимаемые NumPy, – это те, которые также используются другими научными библиотеками Python, такими как pandas, SciPy или Matplotlib. Мы разрабатываем пакет для поддержки большего количества форматов; свяжитесь с нами для получения подробностей.
Документация NumPy хранится в дереве исходного кода. Чтобы добавить ваш документ в базу документации, вы должны загрузить дерево, собрать его, и создать pull request. Если GitHub и pull requests для вас в новинку, ознакомьтесь с нашим Руководство для участников.
Наш язык разметки - reStructuredText (rST), который более сложен, чем Markdown. Sphinx, инструмент, который многие проекты Python используют для сборки и связывания документации проекта, преобразует rST в HTML и другие форматы. Подробнее о rST см. в Краткое руководство по reStructuredText или Введение в reStructuredText
Косвенный вклад#
Если вы встретите внешние материалы, которые могли бы быть полезным дополнением к документации NumPy, сообщите нам об этом открытие issue.
Вам не обязательно вносить вклад здесь, чтобы внести вклад в NumPy. Вы внесли вклад, если написали учебник в своём блоге, создали видео на YouTube или отвечали на вопросы на Stack Overflow и других сайтах.
Стиль документации#
Пользовательская документация#
В целом, мы следуем Руководство по стилю документации для разработчиков Google для Руководства пользователя.
Стиль NumPy регулирует случаи, когда:
Google не даёт указаний, или
Мы предпочитаем не использовать стиль Google
Наши текущие правила:
Мы используем множественное число index как индексы вместо индексыследуя прецеденту
numpy.indices.Для согласованности мы также используем множественное число матрица как матрицы.
Грамматические вопросы, недостаточно освещённые правилами NumPy или Google, решаются в соответствии с разделом «Грамматика и использование» в последнем издании Chicago Manual of Style.
Мы рады быть предупреждён к случаям, которые мы должны добавить в правила стиля NumPy.
Строки документации#
При использовании Sphinx в сочетании с соглашениями NumPy, вы должны использовать numpydoc расширение, чтобы ваши строки документации обрабатывались корректно. Например, Sphinx извлечёт
Parameters раздел из вашей документации и преобразуйте его в список
полей. Используя numpydoc также избежит ошибок reStructuredText, возникающих в Sphinx при встрече с соглашениями NumPy для строк документации, такими как заголовки разделов (например, -------------), которые sphinx не ожидает найти в docstrings.
Доступно с:
Обратите внимание, что для документации в NumPy не обязательно делать
import numpy as np в начале примера.
Пожалуйста, используйте numpydoc стандарт форматирования как показано в их пример.
Документирование кода на C/C++#
NumPy использует Doxygen для разбора специально отформатированных блоков комментариев C/C++. Это генерирует XML-файлы, которые преобразуются с помощью Breathe в RST, который используется Sphinx.
Для завершения процесса документирования требуется три шага:
1. Написание комментариев#
Хотя стиль комментирования всё ещё не установлен для следования, Javadoc предпочтительнее других из-за сходства с текущими существующими неиндексированными блоками комментариев.
Примечание
Пожалуйста, смотрите «Документирование кода».
Вот как выглядит стиль Javadoc:
/**
* This a simple brief.
*
* And the details goes here.
* Multi lines are welcome.
*
* @param num leave a comment for parameter num.
* @param str leave a comment for the second parameter.
* @return leave a comment for the returned value.
*/
int doxy_javadoc_example(int num, const char *str);
И вот как это отображается:
-
int doxy_javadoc_example(int число, const char *str)#
Это простое краткое описание.
И здесь идут детали. Многострочные описания приветствуются.
- Параметры:
число – оставьте комментарий для параметра num.
str – оставьте комментарий для второго параметра.
- Возвращает:
оставить комментарий для возвращаемого значения.
Для однострочного комментария можно использовать три прямые косые черты. Например:
/**
* Template to represent limbo numbers.
*
* Specializations for integer types that are part of nowhere.
* It doesn't support with any real types.
*
* @param Tp Type of the integer. Required to be an integer type.
* @param N Number of elements.
*/
template<typename Tp, std::size_t N>
class DoxyLimbo {
public:
/// Default constructor. Initialize nothing.
DoxyLimbo();
/// Set Default behavior for copy the limbo.
DoxyLimbo(const DoxyLimbo<Tp, N> &l);
/// Returns the raw data for the limbo.
const Tp *data();
protected:
Tp p_data[N]; ///< Example for inline comment.
};
И вот как это отображается:
-
шаблон<typename Tp, std::size_t N>
класс DoxyLimbo# Шаблон для представления чисел лимбо.
Специализации для целочисленных типов, которые нигде не являются частью. Не поддерживается с реальными типами.
- Param Tp:
Тип целого числа. Должен быть целочисленным типом.
- Параметр N:
Количество элементов.
Публичные функции
-
DoxyLimbo()#
Конструктор по умолчанию. Ничего не инициализирует.
Пример#
Рассмотрим следующий пример:
/**
* A comment block contains reST markup.
* @rst
* .. note::
*
* Thanks to Breathe_, we were able to bring it to Doxygen_
*
* Some code example::
*
* int example(int x) {
* return x * 2;
* }
* @endrst
*/
void doxy_reST_example(void);
И вот как это отображается:
-
void doxy_reST_example(void)#
Блок комментариев содержит разметку reST.
Пример кода:
int example(int x) { return x * 2; }
2. Подача Doxygen#
Не все заголовочные файлы собираются автоматически. Необходимо добавить нужные пути к заголовочным файлам C/C++ в подконфигурационных файлах Doxygen.
Подконфигурационные файлы имеют уникальное имя .doxyfile, который обычно можно найти рядом с
каталогами, содержащими документированные заголовки. Вам нужно создать новый файл конфигурации, если
его нет в пути близко (2 уровня) к заголовкам, которые вы хотите добавить.
Подконфигурационные файлы могут принимать любые из Doxygen параметры конфигурации, но не переопределяйте и не переинициализируйте никакие параметры конфигурации, а используйте только оператор конкатенации "+=". Например:
# to specify certain headers
INPUT += @CUR_DIR/header1.h \
@CUR_DIR/header2.h
# to add all headers in certain path
INPUT += @CUR_DIR/to/headers
# to define certain macros
PREDEFINED += C_MACRO(X)=X
# to enable certain branches
PREDEFINED += NPY_HAVE_FEATURE \
NPY_HAVE_FEATURE2
Примечание
@CUR_DIR — это константа шаблона, возвращающая текущий путь каталога подфайла конфигурации.
3. Директивы включения#
Breathe предоставляет широкий набор пользовательских директив для преобразования документов, сгенерированных Doxygen в файлы reST.
Примечание
Для получения дополнительной информации, пожалуйста, ознакомьтесь с "Директивы и конфигурационные переменные”
Общие директивы:#
doxygenfunction
Эта директива генерирует соответствующий вывод для одной функции. Имя функции должно быть уникальным в проекте.
.. doxygenfunction:: <function name>
:outline:
:no-link:
Ознакомьтесь с пример чтобы увидеть это в действии.
doxygenclass
Эта директива генерирует соответствующий вывод для одного класса. Она принимает стандартные опции проекта, пути, структуры и no-link, а также дополнительные опции members, protected-members, private-members, undoc-members, membergroups и members-only:
.. doxygenclass:: <class name>
:members: [...]
:protected-members:
:private-members:
:undoc-members:
:membergroups: ...
:members-only:
:outline:
:no-link:
Ознакомьтесь с документация doxygenclass для получения дополнительных сведений и просмотра в действии.
doxygennamespace
Эта директива генерирует соответствующий вывод для содержимого пространства имён. Она принимает стандартные опции project, path, outline и no-link, а также дополнительные опции content-only, members, protected-members, private-members и undoc-members. Для ссылки на вложенное пространство имён необходимо указать полный путь с пространствами имён, например, foo::bar для пространства имён bar внутри пространства имён foo.
.. doxygennamespace:: <namespace>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
Ознакомьтесь с документация doxygennamespace для получения дополнительных сведений и просмотра в действии.
doxygengroup
Эта директива генерирует соответствующий вывод для содержимого группы doxygen. Группа doxygen может быть объявлена с помощью специальной разметки doxygen в исходных комментариях, как описано в документации doxygen документация по группировке.
Он принимает стандартные опции проекта, пути, структуры и без ссылок, а также дополнительные опции content-only, members, protected-members, private-members и undoc-members.
.. doxygengroup:: <group name>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
:inner:
Ознакомьтесь с документация doxygengroup для получения дополнительных сведений и просмотра в действии.
Директива наследия#
Если функция, модуль или API находится в устаревший режим, означающий, что он сохраняется по причинам обратной совместимости, но не рекомендуется для использования в новом коде. Вы можете использовать .. legacy:: директива.
По умолчанию, если используется без аргументов, директива legacy сгенерирует следующий вывод:
Наследие
Этот подмодуль считается устаревшим и больше не будет получать обновления. Это также может означать, что он будет удален в будущих версиях NumPy.
Мы настоятельно рекомендуем также добавить пользовательское сообщение, например, новый API для замены старого:
.. legacy::
For more details, see :ref:`distutils-status-migration`.
Это сообщение будет добавлено к сообщению по умолчанию и создаст следующий вывод:
Наследие
Этот подмодуль считается устаревшим и больше не будет получать обновления. Это также может означать, что он будет удалён в будущих версиях NumPy. Для получения дополнительной информации см. Статус numpy.distutils и рекомендации по миграции.
Наконец, если вы хотите упомянуть функцию, метод (или любой пользовательский объект) вместо подмодуль, вы можете использовать необязательный аргумент:
.. legacy:: function
Это создаст следующий вывод:
Наследие
Эта функция считается устаревшей и больше не будет получать обновления. Это также может означать, что она будет удалена в будущих версиях NumPy.
Чтение документации#
Ведущая организация технических писателей, Write the Docs, проводит конференции, размещает учебные ресурсы и поддерживает Slack-канал.
«Каждый инженер — тоже писатель», — говорит коллекция ресурсов по техническому письму, который включает бесплатные онлайн-курсы для разработчиков по планированию и написанию документов.
Software Carpentry's миссия — обучение исследователей программному обеспечению. Помимо размещения учебной программы, сайт объясняет, как эффективно представлять идеи.