Проект Матплотлиб

На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.

Краткое описание проекта

Организация с открытым исходным кодом:
Матплотлиб
Технический писатель:
Брюнобельтран
Название проекта:
Улучшение обнаружения функций за счет стандартизации документации «неявных» типов.
Длина проекта:
Длительный ход (5 месяцев)

Описание проекта

Мотивация

Исторически API matplotlib в значительной степени полагался на «неявные типы» строки как перечисления. Помимо имитации API Matlab, эти строки параметров позволяют пользователю передавать семантически богатые значения в качестве аргументов функциям matplotlib без необходимости явного импорта или подробного префикса фактического значения перечисления только для передачи основных параметров графика (т.е. plt.plot(x, y, linestyle='solid') легче вводить и менее избыточен, чем что-то вроде plt.plot(x, y, linestyle=mpl.LineStyle.solid) ).

Многие из этих неявных типов строк как перечислений с тех пор приобрели более сложные функции. Например, linestyle теперь может быть строкой или кортежем из двух последовательностей, а MarkerStyle теперь может быть либо строкой, либо matplotlib.path.Path . Хотя это верно для многих неявных типов, MarkerStyle — единственный (насколько мне известно), который имеет статус обновленного до надлежащего класса Python.

Поскольку эти неявные типы сами по себе не являются классами, Matplotlib исторически приходилось внедрять собственные решения для централизации документации и проверки этих неявных типов (например, шаблон интерполяции docstring.interpd.update и шаблон валидатора cbook._check_in_list соответственно). ) вместо использования стандартных цепочек инструментов, предоставляемых классами Python (например, строк документации и шаблона validate-at __init__ соответственно).

Хотя эти решения хорошо сработали для нас, отсутствие явного местоположения для документирования каждого неявного типа означает, что документацию часто трудно найти, большие таблицы допустимых значений повторяются по всей документации, и часто явное указание области действия неявный тип полностью отсутствует в документации. Возьмем, к примеру, документы plt.plot : в «Примечаниях» в описании метода стилизации форматной строки в стиле Matlab упоминаются параметры linestyle , color и markers . Существует гораздо больше способов передать эти три значения, чем указано, но для многих пользователей это единственный источник понимания того, какие значения возможны для этих параметров, пока они не наткнутся на одно из соответствующих руководств. Таблица атрибутов Line2D включена с целью показать читателю, какие возможности управления сюжетом у него есть. Однако, хотя запись linestyle хорошо связывается с Line2D.set_linestyle (требуется два щелчка мышью), где описаны возможные входные данные, записи color и markers этого не делают. color просто ссылается на Line2D.set_color , что не дает никакой информации о том, какие типы входных данных вообще разрешены.

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

Конечная цель

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

Если снова использовать пример linestyle , то, что нам нужно в документации LineCollection это просто:

  1. Ссылка на полную документацию для допустимых входных данных (комбинация документов, найденных в Line2D.set_linestyle и учебнике по стилям линий ).
  2. Простое описание того, для чего предназначен параметр. Для опытных пользователей matplotlib это очевидно из названия параметра, но для новых пользователей это не обязательно.

То, как это будет выглядеть в реальной документации LineCollection , - это просто python """""" linestyles: `LineStyle` or list thereof, default: :rc:`lines.linestyle` ('-') A description of whether the stroke used to draw each line in the collection is dashed, dotted or solid, or some combination thereof. """""" где ссылка на тип LineStyle будет разрешена Sphinx, чтобы указать на единый, авторитетный и полный набор документации о том, как Matplotlib обрабатывает стили линий.

Преимущества

Некоторые мощные особенности этого подхода включают в себя

  1. Полное представление того, на что способна каждая функция, в виде простого текста (без необходимости щелчков мышью).
  2. Сделать параметр по умолчанию видимым (без щелчков мышью). Увидеть опцию по умолчанию часто бывает достаточно, чтобы оживить память вернувшихся пользователей.
  3. Сделайте полное описание «самых распространенных» и «самых простых» вариантов параметра, легко доступных при просмотре (одним щелчком мыши).
  4. Сделайте процесс открытия более мощных функций и методов ввода таким же простым, как «прокрутка вниз», чтобы увидеть более сложные параметры (все еще одним щелчком мыши).
  5. Обеспечьте централизованную стратегию для связывания документов «API» верхнего уровня с соответствующими «руководствами».
  6. Избегайте расширения документации API, когда сканирование множества возможных вариантов каждого параметра делает отдельные строки документации громоздкими.

Другими преимуществами этого подхода по сравнению с текущими документами являются:

  1. Документы с меньшей вероятностью устареют из-за централизации.
  2. Канонизация многих «неявных стандартов» matplotlib (например, что такое «границы» и «экстенты»), которые в настоящее время необходимо изучать, читая код.
  3. Этот процесс позволит выявить проблемы с согласованностью API таким образом, чтобы их было легче отслеживать с помощью трекера проблем GitHub, что поможет в процессе улучшения нашего API.
  4. Ускорение создания документов благодаря значительному уменьшению объема текста, который необходимо проанализировать.

Выполнение

Улучшения, описанные выше, потребуют двух крупных усилий, для которых преданный технический писатель будет иметь неоценимое значение. Первый — создать одну централизованную страницу «учебника» для каждого неявного типа. Это потребует работы с основной командой разработчиков для определения конкретного списка неявных типов, документация которых будет ценна для пользователей (обычно потому, что они содержат мощные, скрытые функции нашей библиотеки, документацию по которой в настоящее время можно найти только в труднодоступных местах). в учебниках). Затем для каждого неявного типа я синтезирую различные соответствующие учебные пособия, документацию по API и страницы с примерами в единый авторитетный источник документации, который можно ссылаться на любое место, где упоминается этот конкретный тип.

Как только централизованная документация для данного неявного типа завершена, начинается вторая важная работа: замена существующей документации API ссылками на новую документацию с прицелом на то, чтобы максимально упростить процесс фактического использования этой новой документации как для тех, кто с помощью встроенной в Python утилиты help() и для тех, кто просматривает нашу документацию в Интернете.

Хотя точный формат предлагаемой здесь документации может меняться по мере развития этого проекта, я работал с основной командой Matplotlib во время их еженедельных «звонков разработчиков», чтобы прийти к консенсусу о том, что предложенная здесь стратегия является наиболее целесообразной и полезной. и технически удобный подход для начала документирования этих «неявных типов» (примечания по этим вызовам доступны на hackmd ). Я буду использовать существующую инфраструктуру «учебников» на начальных этапах создания централизованной документации для каждого неявного типа, что позволит мне легко ссылаться на эти страницы следующим образом, без необходимости создавать какие-либо новые общедоступные классы (опять же, используя документацию LineCollection ). в качестве примера):

""""""
linestyles: LineStyle or list thereof, default: :rc:`lines.linestyle` ('-')
    A description of whether the stroke used to draw each line in the collection
    is dashed, dotted or solid, or some combination thereof. For a full
    description of possible LineStyle's, see :doc:`tutorials/types/linestyle`.
""""""

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

Наконец, предварительный список неявных типов, которые я предлагаю документировать в этом сезоне документации Google:

  1. capstyle
  2. joinstyle
  3. bounds
  4. extents
  5. linestyle
  6. colors / lists of colors
  7. colornorm/colormap
  8. tick formatters

Действующую версию этого документа можно найти в нашем Обсуждении .