Как внести вклад в документацию NumPy

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

Существуют формулы для написания полезных документов, и четыре формулы охватывают практически все. Существует четыре формулы, потому что существует четыре категории документов – tutorial, how-to guide, explanation, и reference. Понимание того, что документы делятся таким образом, принадлежит Даньеле Проциде и его фреймворку Diátaxis. Когда вы начинаете документ или предлагаете его, имейте в виду, к какому типу он относится.

Учебники NumPy

В дополнение к документации, которая является частью исходного дерева NumPy, вы можете отправлять контент в формате Jupyter Notebook на страницу Учебники NumPy. Этот набор учебных материалов и учебных пособий призван предоставить высококачественные ресурсы от проекта NumPy, как для самостоятельного обучения, так и для преподавания курсов. Эти ресурсы разрабатываются в отдельном репозитории GitHub, numpy-tutorials, где вы можете ознакомиться с существующими блокнотами, открыть вопросы, чтобы предложить новые темы, или отправить свои учебные материалы в виде запросов на вытягивание.

Больше о внесении вклада

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

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

На данный момент форматы данных, принимаемые NumPy, — это те же форматы, которые используются другими Python-библиотеками для научных вычислений, такими как pandas, SciPy или Matplotlib. Мы разрабатываем пакет для поддержки большего количества форматов; обратитесь к нам за подробностями.

Документация NumPy хранится в исходном дереве кода. Чтобы включить ваш документ в базу данных документации, необходимо загрузить дерево, собрать его и отправить запрос на вытягивание. Если GitHub и запросы на вытягивание вам незнакомы, ознакомьтесь с нашим Руководством по внесению вклада.

Наш язык разметки — reStructuredText (rST), который более сложен, чем Markdown. Sphinx, инструмент, который многие Python-проекты используют для создания и связывания документации проекта, преобразует rST в HTML и другие форматы. Дополнительные сведения о rST можно найти в кратком руководстве по reStructuredText или в руководстве по reStructuredText

Документация для пользователя

• В общем случае, мы следуем руководству по стилю документации разработчиков Google для руководства пользователя.

• Стиль NumPy регулирует случаи, когда:

  • У Google нет руководства, или
  • Мы предпочитаем не использовать стиль Google

  Наши текущие правила:

  • Мы склоняем index к indices, а не к indexes, следуя прецеденту numpy.indices.
  • Для согласованности мы также склоняем matrix к matrices.
• Грамматические вопросы, недостаточно подробно рассмотренные в правилах NumPy или Google, решаются на основе раздела «Грамматика и использование» в последнем издании Справочника по стилю Чикагского университета.
• Мы приветствуем уведомления о случаях, которые необходимо добавить в правила стиля NumPy.

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

При использовании Sphinx в сочетании с конвенциями NumPy, вы должны использовать numpydoc расширение, чтобы ваши строки документации обрабатывались правильно. Например, Sphinx извлечет Parameters раздел из вашей строки документации и преобразует его в список полей. Использование numpydoc также позволит избежать ошибок reStructuredText, создаваемых обычным Sphinx, когда он сталкивается с соглашениями NumPy для строк документации, такими как заголовки разделов (например, -------------), которых Sphinx не ожидает найти в строках документации.

Его можно получить от:

• numpydoc на PyPI
• numpydoc на GitHub

Обратите внимание, что для документации внутри NumPy не обязательно выполнять import numpy as np в начале примера.

Пожалуйста, используйте numpydoc стандарт форматирования, как показано в их примере.

Документирование кода C/C++

NumPy использует Doxygen для анализа специально отформатированных блоков комментариев C/C++. Это создаёт XML-файлы, которые преобразуются с помощью Breathe в RST, используемый Sphinx.

Процесс документирования состоит из трёх этапов:

/**
 * 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 num, const char *str)
- int doxy_javadoc_example(int num, const char *str)
- int doxy_javadoc_example(int num, const char *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.
};

/**
 * 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)
- void doxy_reST_example(void)
- void doxy_reST_example(void)

Директива устаревшего кода

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

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

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

.. legacy::

   For more details, see :ref:`distutils-status-migration`.

Это сообщение будет добавлено к стандартному сообщению и создаст следующий вывод:

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

.. legacy:: function

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