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

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

  • использование Gitpod для среды разработки pandas

  • создание персональной форк-копии репозитория pandas на GitHub

  • краткий обзор pandas и VSCode

  • работа над документацией pandas в Gitpod

Gitpod#

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

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

Чтобы использовать Gitpod, вам нужно установить приложение Gitpod в вашем аккаунте GitHub, поэтому если у вас еще нет аккаунта, сначала нужно его создать.

Чтобы начать, просто войдите в систему на Gitpod, и предоставьте соответствующие разрешения GitHub.

Мы создали среду Python 3.10, и все зависимости для разработки будут установлены при запуске среды.

Форк репозитория pandas#

Лучший способ работать над pandas как контрибьютор — сначала создать форк репозитория.

  1. Перейдите к репозиторий pandas на GitHub и создайте собственную ветку.

  2. Перейдите к своей форке. Ваша форка будет иметь URL-адрес вида noatamir/pandas-dev, за исключением замены вашего имени пользователя GitHub на noatamir.

Запуск Gitpod#

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

pandas repository with Gitpod button screenshot

  1. Если вы установите расширение - вы можете нажать Gitpod кнопка для запуска нового рабочего пространства.

  2. В качестве альтернативы, если вы не хотите устанавливать расширение браузера, вы можете посетить https://gitpod.io/#https://github.com/USERNAME/pandas замена USERNAME с вашим именем пользователя GitHub.

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

  4. После завершения сборки вы будете перенаправлены в рабочее пространство, включая редактор VSCode и все зависимости, необходимые для работы с pandas. При первом запуске рабочего пространства вы заметите, что там могут выполняться некоторые действия. Это обеспечит установку разрабатываемой версии pandas.

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

    $ python -m pytest pandas

    Обратите внимание, что эта команда выполняется долго, поэтому после подтверждения ее работы вы можете отменить ее с помощью ctrl-c.

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

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

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

Gitpod workspace screenshot

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

  1. Ваш текущий интерпретатор Python - по умолчанию, это pandas-dev и должны отображаться в строке состояния и на вашем терминале. Вам не нужно активировать окружение conda, так как оно всегда будет активировано для вас.

  2. Ваша текущая ветка всегда отображается в строке состояния. Вы также можете использовать эту кнопку для изменения или создания веток.

  3. Расширение GitHub Pull Requests - вы можете использовать его для работы с Pull Requests из вашего рабочего пространства.

  4. Расширения Marketplace - мы добавили некоторые важные расширения в pandas Gitpod. Тем не менее, вы также можете установить другие расширения или темы подсветки синтаксиса для своего пользователя, и они будут сохранены для вас.

  5. Ваш рабочий каталог - по умолчанию это /workspace/pandas-dev. Не изменяйте это поскольку это единственный каталог, сохраняемый в Gitpod.

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

Рабочий процесс разработки с Gitpod#

The Вклад в pandas раздел этой документации содержит информацию о процессе разработки pandas. Обязательно ознакомьтесь с этим перед работой над вашими вкладами.

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

  1. Вам не нужно настраивать имя пользователя и email в git, так как это должно быть сделано автоматически при аутентификации через GitHub. Исключение составляет случай, когда вы используете функцию GitHub для скрытия email-адреса. Проверить конфигурацию git можно с помощью команды git config --list в вашем терминале. Используйте git config --global user.email “your-secret-email@users.noreply.github.com” чтобы установить ваш адрес электронной почты на тот, который вы используете для коммитов в вашем профиле github.

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

    Gitpod workspace branches plugin screenshot

Рендеринг документации pandas#

Подробную документацию о том, как работает рендеринг документации с помощью Sphinx, можно найти в Как собрать документацию pandas раздел. Чтобы собрать полную документацию, вам нужно выполнить следующую команду в /doc каталог:

$ cd doc
$ python make.py html

Альтернативно вы можете построить одну страницу с:

python make.py --single development/contributing_gitpod.rst

У вас есть два основных варианта для отображения документации в Gitpod.

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

  1. Просмотрите документацию в pandas/doc/build/html.

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

    Gitpod workspace VSCode start live serve screenshot

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

  4. Чтобы остановить сервер, нажмите на Порт: 5500 кнопка на строке состояния.

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

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

Примечание

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

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

  2. Открыть палитру команд VSCode с Cmd-Shift-P в Mac или Ctrl-Shift-P в Linux и Windows. Начните вводить «restructured» и выберите либо «Open preview», либо «Open preview to the Side».

    Gitpod workspace VSCode open rst screenshot

  3. Во время работы над документом вы будете видеть его живой рендеринг в редакторе.

    Gitpod workspace VSCode rst rendering screenshot

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

Часто задаваемые вопросы и устранение неполадок#

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

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

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

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

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

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

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

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

Gitpod integrations - edit GH permissions screenshot

Как долго моя рабочая область остается активной, если я её не использую?#

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

Мой терминал пуст - нет курсора и он полностью не отвечает#

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

  1. Создать совершенно новую рабочую область Gitpod.

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

Gitpod dashboard and workspace menu screenshot

Я прошел аутентификацию через GitHub, но все еще не могу коммитить в репозиторий через Gitpod.#

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

Gitpod integrations - edit GH repository permissions screenshot

Благодарности#

Эта страница слегка адаптирована из NumPy проект .