Продемонстрируйте свою работу на веб-сайте индивидуального проекта

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

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

https://<username>.github.io/<repository_name>

1. Создайте сиротский филиал

Для простоты мы не хотим, чтобы пользователь, клонирующий нашу ветку master, также видел все файлы HTML / CSS / JS, которые будут связаны с веб-сайтом нашего проекта. Чтобы обойти эту проблему, мы можем использовать так называемую «сиротскую ветвь» - по сути, ветвь, которая находится в корне дерева без каких-либо предыдущих коммитов. Затем, если все файлы нашего веб-сайта находятся в сиротской ветке, при клонировании репозитория по умолчанию будут отображаться только файлы в master (хотя любой может по-прежнему перейти в ветку веб-сайта, если пожелает).

Мы создаем нашу сиротскую ветку, которую мы назовем gh-pages с помощью следующей команды:

git checkout --orphan gh-pages

2. Очистка ветки gh-pages

Это та часть, которая мне показалась самой страшной, когда я впервые это сделала. Вы собираетесь удалить все из папки, чтобы очистить ветку gh-pages. Не волнуйтесь, ваши master файлы веток никуда не делись! Используйте следующую команду:

git rm -rf .

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

3. Добавить файлы веб-страниц

Теперь добавьте свой index.html файл вместе с любыми таблицами стилей CSS, Javascript и другими ресурсами, которые могут понадобиться вашему веб-сайту, в ваш локальный рабочий каталог. Теперь подготовьте и зафиксируйте свои изменения:

git add *
git commit -m "Commit Message"

Наконец, мы хотим убедиться, что мы отправляем наши изменения в соответствующую ветку (gh-pages).

git push origin gh-pages

4. Настройка страниц GitHub

Перейдите в онлайн-репозиторий GitHub и перейдите к настройкам. Прокрутив страницу вниз, вы увидите раздел под названием «Страницы GitHub». Под областью под названием «Источник» вы увидите раскрывающееся меню, которое вы можете использовать для выбора ветви, из которой вы хотите создать свой веб-сайт. Мы продолжим и выберем gh-pages.

Подождите пару минут и БАМ! Ваш сайт должен работать! Откройте в браузере https://<username>.github.io/<repo_name>, чтобы увидеть свое чудесное творение.

5. Настройте отдельные каталоги для филиалов

Продолжая редактировать свой веб-сайт и исходный код, вы быстро заметите, что вам придется постоянно переключаться между двумя ветвями:

# Switch to master branch
git checkout master
# Switch to gh-pages branch
git checkout gh-pages

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

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

# Remove git tracking
rm -rf .git*

Теперь давайте повторно клонируем наш репозиторий в подкаталог. Мы назовем этот каталог source, и в нем будет храниться весь наш исходный код.

git clone https://github.com/<username>/<reponame> source

Вы заметите, что теперь у вас есть папка с именем source со всеми файлами из ветки master. Теперь давайте создадим новый каталог с именем gh-pages, в котором будут размещены все файлы нашего веб-сайта:

mkdir gh-pages

Перейдите в исходную папку:

cd source/

Теперь мы используем worktree и делаем наш каталог gh-pages соответствующим удаленной ветке gh-pages.

git worktree add ../gh-pages gh-pages

И вы сделали! Теперь вы заметите, что когда вы перейдете в каталог gh-pages, вы увидите только файлы в ветке gh-pages, а если вы запустите команду git branch, вы увидите, что находитесь в master, когда в каталоге source и gh-pages в каталоге gh-pages.

Теперь вы можете свободно редактировать веб-сайт репозитория и исходный код одновременно, и у вас есть отличная целевая страница для вашего проекта на GitHub!

Заключительные замечания

Спасибо за чтение! Вы можете увидеть некоторые из моих работ на моей личной странице GitHub. Я ценю любую обратную связь, и вы можете найти меня в Твиттере и связаться со мной в LinkedIn, чтобы получать больше обновлений и статей.