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

Это руководство поможет вам определиться с тем, что внести вклад, и как предоставить его в официальную документацию NumPy.

Встречи команды по документации

Сообщество NumPy поставило перед собой твердую цель улучшить свою документацию. Мы проводим регулярные встречи по документации в Zoom (даты объявляются на почтовом списке numpy-discussion), и все желающие могут принять участие. Обращайтесь, если у вас есть вопросы или вам нужна помощь в первых шагах – мы с удовольствием поможем. Протоколы ведутся на hackmd.io и хранятся в репозитории NumPy Archive.

Что нужно

Подробная информация содержится в документации NumPy. Документация справки API генерируется непосредственно из строк документации в коде при создании документации построении. Хотя мы в основном имеем полную справочную документацию для каждой функции и класса, доступных пользователям, для некоторых из них отсутствуют примеры использования.

Нам не хватает документов с более широким охватом – учебников, руководств и объяснений. Еще одним способом внести свой вклад является сообщение о проблемах. Мы обсуждаем оба этих аспекта.

Внесение исправлений

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

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

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

Явные ошибки формулировок (например, пропущенное «не») относятся к категории опечаток, но другие переформулировки – даже для грамматики – требуют оценки, что повышает планку. Сначала представьте исправление как вопрос, чтобы проверить воду.

Внесение новых страниц

Ваши трудности при использовании наших документов – лучшее руководство о том, что необходимо исправить.

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

Если вы ищете темы, наша официальная дорожная карта для документации – это Предложение по улучшению NumPy (NEP), NEP 44 – Реструктуризация документации NumPy. В нём определены области, в которых нашей документации нужна помощь, и перечислены несколько добавлений, которые мы хотели бы увидеть, включая Jupyter ноутбуки.

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

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

Учебники NumPy

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

Дополнительная информация о внесении вклада

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

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

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

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

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

Вклад косвенно

Если вы встретите внешний материал, который будет полезен для добавления в документацию NumPy, сообщите нам об этом, открыв вопрос.

Вам не нужно вносить вклад сюда, чтобы внести вклад в NumPy. Вы внесли вклад, если написали учебник на своем блоге, создали видео на YouTube или ответили на вопросы на Stack Overflow и других сайтах.

Чтение документации

• Ведущая организация технических писателей, Write the Docs, проводит конференции, предоставляет учебные ресурсы и ведет канал Slack.
• «Каждый инженер также является писателем», – заявляет Google в сборнике ресурсов по техническому письму, который включает бесплатные онлайн-курсы для разработчиков по планированию и написанию документов.
• Software Carpentry ставит перед собой задачу обучать исследователей программному обеспечению. Помимо размещения учебного плана, на сайте объясняется, как эффективно представлять идеи.