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

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

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

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

Что нужно

В документации NumPy подробно описаны все детали. Документация по API генерируется непосредственно из docstrings в коде при создании документации.

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

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

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

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

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

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

Создание новых страниц

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

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

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

Вы можете найти более масштабные запланированные и находящиеся в разработке идеи на странице проекта GitHub.

Формулы написания

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

Больше о вкладе

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

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

Пока что 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 посвящена обучению исследователей программированию. Помимо размещения учебной программы, сайт объясняет, как эффективно представлять идеи.