Использование интерактивных записных книжек внутри среды IDE.

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

GT Documenter - это гибкий инструмент, который позволяет создавать и использовать документацию по коду и учебные пособия прямо в среде IDE. Это позволяет:

  • документация по существующему коду
  • учебные пособия
  • интерактивные записные книжки с данными

В этой статье рассматривается использование GT Documenter для создания интерактивных руководств.

Перспективы

Учебники - часть повседневной жизни разработчика. Мы полагаемся на них, чтобы представить другим возможности наших библиотек, узнать, как использовать API-интерфейсы, или задокументировать, что делают наши программные системы. Чаще всего чтение руководств происходит за пределами наших IDE, в основном в веб-браузерах, учитывая, что подавляющее большинство руководств публикуется с помощью сообщений в блогах или различных блокнотов.

С одной стороны, это делает их легкодоступными. С другой стороны, это затрудняет, если не делает невозможным, экспериментировать и следовать руководствам непосредственно в наших IDE. И наличие учебных пособий, доступных непосредственно в среде IDE, может быть ценным: именно там живет наш код; мы можем отклониться от учебника и поэкспериментировать; мы можем включить и использовать наш код. Если нам нужно выходить за пределы IDE каждый раз, когда мы хотим следовать руководству, «I» в IDE не работает.

Учебники вне IDE

Внедрение руководств в нашу среду IDE в большинстве случаев включает копирование и вставку. Часто код может быть неполным, может потребоваться некоторая настройка или дополнительные служебные методы и классы. Даже если мы получим код, может не быть прямого способа выполнить фрагменты кода и изучить возвращаемые ими значения.

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

Пошаговое выполнение этого руководства требует, чтобы читатели не только переместили код из учебника в среду IDE, но и знали, как определять методы тестирования (размещать их в новых классах, являющихся подклассом TestCase) и использовать Test Runner , шаги, явно не описанные в руководстве. Хотя эти недостающие детали очевидны для некоторых читателей, они могут мешать другим. Авторы учебников могут легко вводить предположения, о которых читатели не узнают.

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

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

Интерактивные руководства в среде IDE

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

GT Documenter - это инструмент из Glamorous Toolkit, предназначенный для глубокого встраивания записных книжек в среду IDE. Мы используем его далее, чтобы показать пример преобразования части учебника Примеры программного обеспечения, упомянутого ранее, в записную книжку. Эту записную книжку можно открыть из Glamorous Toolkit, выбрав пункт меню GToolkit Scenery → Примеры Tutorial - Face API.

Код загрузки

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

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

Если мы применим эти изменения и переключимся на представление Diff второго фрагмента кода, мы увидим, что рефакторинг заключается в добавлении двух строк кода.

Теперь, если мы поэкспериментируем и изменим код учебника, мы сможем в любой момент вернуться и использовать представление Diff, чтобы увидеть, чем наш код отличается от кода учебника. Получение различий прямо внутри ноутбука возможно, поскольку ноутбук живет внутри IDE, а не полностью не осведомлен о нашей среде.

Выполнение кода

Блокноты также включают фрагменты кода, которые могут быть выполнены читателем. Например, поскольку в учебнике Примеры программного обеспечения используется система обнаружения лиц, нам часто требуется создавать объекты, представляющие лица, к которым прикреплены ориентиры (положение носа, глаз, рта, и т. Д.). Мы можем сделать это, имея код непосредственно в записной книжке. Когда код затем выполняется, созданный объект внедряется непосредственно в записную книжку и отображается с помощью инспектора объектов.

Для приведенного выше фрагмента кода, помимо обнаружения возникших исключений, невозможно проверить, работает ли фрагмент должным образом. Также повторное использование этого фрагмента в другой части записной книжки требует от нас его дублирования. Чтобы улучшить это, вместо прямого встраивания фрагментов кода в записную книжку можно добавить другой способ - сослаться на пример метода, содержащий этот код. Ниже код метода faceEinsteinWithLandmarks встроен в записную книжку. При выполнении объект, возвращаемый этим методом, отображается рядом с ним.

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

Примеры методов не живут внутри записной книжки. На них ссылаются только из записной книжки, но они находятся в нашей рабочей области, как методы тестирования. Поскольку блокнот глубоко интегрирован в среду IDE, он может обращаться к этим методам и выполнять их. Кроме того, поскольку ноутбук находится внутри IDE, он может повторно использовать свои инструменты. Результат выполнения двух предыдущих фрагментов отображается с помощью инспектора объектов. Это тот же инструмент, который используется IDE в отладчике.

Импровизированные исследования

Во многих случаях записные книжки ограничивают читателей в их исследованиях, поскольку они требуют от них перемещаться по записной книжке исключительно сверху вниз. Если разработчики обнаруживают в записной книжке интересные фрагменты кода, данные или объекты, их возможности для дальнейшего взаимодействия с ними непосредственно в записной книжке ограничены. Для облегчения импровизированных исследований GT Documenter позволяет пользователям глубже погружаться в любой объект, присутствующий в записной книжке.

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

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

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

Заворачивать

Учебники широко используются во время разработки программного обеспечения. Несмотря на это, они довольно часто используются вне IDE, инструментов, которые разработчики используют ежедневно для формирования кода своих систем. Чтобы сделать IDE по-настоящему интегрированными, нам нужно глубоко встроить создание и использование учебных пособий в их ядро.

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