Использование Gitpod для разработки NumPy

Этот раздел документации проведет вас через:

• использование GitPod в качестве среды разработки NumPy
• создание личной вилки репозитория NumPy на GitHub
• быстрый обзор Gitpod и VSCode
• работа с документацией NumPy в Gitpod

Gitpod

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

Интеграция Gitpod с GitHub

Для использования Gitpod вам потребуется приложение Gitpod, установленное в вашей учетной записи GitHub. Если у вас еще нет учетной записи, вам необходимо создать её сначала.

Перейдите на сайт Gitpod и нажмите кнопку Продолжить с GitHub. Вы будете перенаправлены на страницу аутентификации GitHub. Вам затем будет предложено установить приложение Gitpod GitHub app.

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

Это установит необходимые хуки для интеграции.

Создание вилки репозитория NumPy

Лучший способ работы над NumPy как участником — создание вилки репозитория.

1. Перейдите к репозиторию NumPy на GitHub и создайте свою вилку.
2. Перейдите к вашей вилке. Ваша вилка будет иметь URL-адрес, например, https://github.com/melissawm/NumPy, за исключением того, что ваше имя пользователя GitHub будет стоять вместо melissawm.

Запуск Gitpod

После аутентификации в Gitpod через GitHub, вы можете установить расширение Gitpod для браузера, которое добавит кнопку Gitpod рядом с кнопкой Код в репозитории:

1. Если вы установили расширение, вы можете нажать кнопку Gitpod, чтобы запустить новую рабочую область.
2. В качестве альтернативы, если вы не хотите устанавливать расширение браузера, вы можете посетить https://gitpod.io/#https://github.com/USERNAME/NumPy, заменив USERNAME на ваше имя пользователя GitHub.
3. В обоих случаях это откроет новую вкладку в вашем веб-браузере и начнет создание вашей среды разработки. Пожалуйста, обратите внимание, что это может занять несколько минут.
4. По завершении сборки вы будете перенаправлены в свою рабочую область, включая редактор VSCode и все необходимые зависимости для работы с NumPy. В первый раз, когда вы запускаете рабочую область, вы заметите, что могут выполняться некоторые действия. Это гарантирует, что у вас установлена разработочная версия NumPy, и документация предварительно построена для вас.

5. Когда ваша рабочая область готова, вы можете протестировать сборку, введя:

   $ python runtests.py -v
   

runtests.py — это еще один скрипт в корневом каталоге NumPy. Он выполняет набор тестов, которые гарантируют, что NumPy работает должным образом, а -v активирует опцию --verbose для отображения всех результатов тестов.

Быстрый обзор рабочей области

Gitpod использует VSCode в качестве редактора. Если вы раньше не пользовались этим редактором, вы можете ознакомиться с руководством по началу работы документацией VSCode, чтобы ознакомиться с ним.

Ваша рабочая область будет похожа на изображение ниже:

Мы отметили некоторые важные разделы в редакторе:

1. Ваш текущий интерпретатор Python — по умолчанию это numpy-dev и он должен отображаться в строке состояния и в вашем терминале. Вам не нужно активировать среду conda, так как она всегда будет активирована для вас.
2. Ваш текущий ветвь всегда отображается в строке состояния. Вы также можете использовать эту кнопку для изменения или создания веток.
3. Расширение GitHub Pull Requests — вы можете использовать его для работы с запросами на вытягивание из вашей рабочей области.
4. Расширения Marketplace — мы добавили несколько важных расширений в Gitpod NumPy. Вы также можете установить другие расширения или темы синтаксического выделения для вашего пользователя, и они будут сохранены за вами.
5. Каталог вашей рабочей области — по умолчанию он /workspace/numpy. Не изменяйте его, так как это единственный каталог, сохраняемый в Gitpod.

Мы также предварительно установили несколько инструментов и расширений VSCode, которые помогут в процессе разработки:

• GitHub CLI
• Расширение VSCode rst
• Расширение VSCode Live server
• Расширение VSCode Gitlens
• Расширение VSCode autodocstrings
• Расширение VSCode Git Graph

Процесс разработки с Gitpod

Раздел Процесс разработки этой документации содержит информацию о процессе разработки NumPy. Убедитесь, что вы ознакомились с ним перед началом работы над своими вкладами.

При использовании Gitpod Git предварительно настроен для вас:

1. Вам не нужно настраивать имя пользователя и адрес электронной почты Git, так как это должно быть сделано за вас при аутентификации через GitHub. Вы можете проверить конфигурацию Git командой git config --list в вашем терминале.

2. Поскольку вы запустили рабочую область из своей вилки NumPy, у вас по умолчанию добавлены как удалённые ветви upstream и origin. Вы можете проверить это, набрав git remote в своём терминале или нажав на имя ветви в строке состояния (см. изображение ниже).

   

Отображение документации NumPy

Подробную документацию о том, как работает отображение документации с помощью Sphinx, можно найти в разделе Создание документации API и справочной документации NumPy.

Документация предварительно построена во время инициализации вашей рабочей области. После завершения этой задачи у вас есть два основных варианта отображения документации в Gitpod.

Вариант 1: Использование Liveserve

1. Просмотрите документацию в NumPy/doc/build/html. Вы можете начать с index.html и просматривать или сразу перейти к интересуемому файлу.

2. Чтобы увидеть рендер страницы, вы можете щелкнуть правой кнопкой мыши по файлу .html и нажать Открыть с помощью Live Serve. В качестве альтернативы, вы можете открыть файл в редакторе и нажать кнопку Запустить в браузере в строке состояния.

   
3. Всплывающее окно откроет браузер справа от редактора. Мы рекомендуем закрыть его и нажать на кнопку Открыть в браузере в всплывающем окне.
4. Чтобы остановить сервер, нажмите кнопку Порт: 5500 в строке состояния.

Вариант 2: Использование расширения rst

Быстрый и простой способ увидеть изменения в файле .rst при работе с ним — использование расширения rst с docutils.

1. Откройте любой из исходных файлов документации, расположенных в doc/source в редакторе.

2. Откройте палитру команд VSCode с помощью Cmd-Shift-P на Mac или Ctrl-Shift-P на Linux и Windows. Начните вводить «restructured» и выберите «Открыть предварительный просмотр» или «Открыть предварительный просмотр справа».

   

3. При работе с документом вы увидите его живое отображение в редакторе.

   

Если вы хотите увидеть конечный результат с темой html, вам необходимо пересобрать документацию с помощью make html и использовать Live Serve, как описано в варианте 1.

Вопросы и ответы и устранение неполадок

Насколько долго хранится моя рабочая область Gitpod?

Остановленная рабочая область будет сохраняться в течение 14 дней и будет удалена в дальнейшем, если вы её не используете.

Могу ли я вернуться к предыдущей рабочей области?

Да, предположим, что вы ненадолго отошли и хотите продолжить работу над своими contributions в NumPy. Вам нужно перейти по ссылке https://gitpod.io/workspaces и нажать на рабочий стол, который вы хотите снова запустить. Все ваши изменения будут там, где вы их оставили.

Могу ли я установить дополнительные расширения VSCode?

Конечно! Все установленные вами расширения будут установлены в вашем собственном рабочем пространстве и сохранены.

Я зарегистрировался в Gitpod, но по-прежнему не вижу кнопку Gitpod в моих репозиториях.

Перейдите по ссылке https://gitpod.io/integrations и убедитесь, что вы вошли в систему. Наведите курсор на GitHub и нажмите на три кнопки, которые появятся справа. Нажмите на изменение разрешений и убедитесь, что у вас отмечены user:email, read:user, и public_repo. Нажмите Обновить разрешения и подтвердите изменения на странице приложения GitHub.

Сколько времени моё рабочее пространство остаётся активным, если я им не пользуюсь?

Если вы оставляете своё рабочее пространство открытым в вкладке браузера, но не взаимодействуете с ним, оно будет закрыто через 30 минут. Если вы закроете вкладку браузера, оно будет закрыто через 3 минуты.

Моя консоль пуста — нет курсора, и она полностью не реагирует

К сожалению, это известная проблема со стороны Gitpod. Вы можете решить эту проблему двумя способами:

1. Создайте новый рабочий стол Gitpod.
2. Перейдите в свой панель управления Gitpod и найдите запущенное рабочее пространство. Наведите на него курсор и нажмите на меню три точки, а затем на Остановить. Когда рабочее пространство полностью остановится, вы можете нажать на его имя, чтобы перезапустить его снова.

Я авторизовался через GitHub, но по-прежнему не могу сделать коммит в репозиторий через Gitpod.

Перейдите по ссылке https://gitpod.io/integrations и убедитесь, что вы вошли в систему. Наведите курсор на GitHub и нажмите на три кнопки, которые появятся справа. Нажмите на изменение разрешений и убедитесь, что у вас отмечен public_repo. Нажмите Обновить разрешения и подтвердите изменения на странице приложения GitHub.