GitHub и Read The Docs¶

Как скопировать проект с github на компьютер

Если вы, как и я, решили освоить git, то скорее всего у вас возникнет желание разместить свой проект на GitHub.com для публичного доступа.

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

Работа с Read The Docs¶

Read the Docs (https://readthedocs.org) служит для хранения и публикации документации, позволяет легко в ней ориентироваться и делает её доступной для полноценного поиска. Можно импортировать документацию из проекта, используя любую известную систему контроля версий: Mercurial, Git, Subversion и Bazaar.

Read The Docs поддерживает webhooks , так что документация может быть обновлена сразу после добавления в репозиторий нового кода. Также есть поддержка версий, поэтому можно собирать отдельные варианты (в том числе отдельные локализации) документации для тэгов и веток, которые есть в репозитории.

Регистрация¶

Read the Docs полностью бесплатен, регистрация на нём не занимает много времени.

Привязка к GitHub¶

После регистрации можно привязать свой аккаунт на GitHub или Bitbucket.

Создание проекта¶

Прежде чем выгрузить свой проект на Read the Docs, его необходимо создать и загрузить на GitHub. Структура репозитория должна содержать папку docs , в которой и будет находиться проект Sphinx (т.е. команду sphinx-quickstart нужно запускать в папке docs ).

После создания Sphinx-проекта и генерации документации, загружаем репозиторий на GitHub.

Импорт проекта¶

После создания проекта и выгрузки его на GitHub в панели управления Read the Docs нажимаем Import a project .

Синхронизируемся с GitHub и выбираем репозиторий, документация из которого будет опубликована на Read the Docs. Нажимаем кнопку Create .

Далее будет предложено выбрать Имя проекта (это будет часть URL-адреса документации Имя-проекта.readthedocs.org), Тип репозитория и также можно установить галочку Edit advanced project options для включения расширенных настроек.

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

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

После выбора всех настроек будет произведена первая сборка руководства.

Так выглядит стандартная тема оформления Read the Docs, при желании можно использовать любую другую (см. Смена HTML-темы ):

Автоматическая публикация¶

Для включения автоматической публикации документации на Read The Docs при обновлении репозитория GitHub, перейдите в репозиторий проекта на GitHub в раздел Settings .

Выберите пункт Webhooks & Services и добавьте сервис Read the Docs.

Не путайте автоматическую публикацию с автоматической сборкой (генерацией) самой документации Sphinx, об этом подробнее смотрите раздел Автоматическая сборка .

Настройка¶

В панели управления проектом на Read the Docs в разделе Админ можно изменить настройки проекта, добавить новые версии документации, назначить кураторов и т.д.

Несколько версий документации¶

Версии документации создаются на основе веток Git-репозитория, подробнее смотрите Ветвление .

Ошибки сборки¶

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

Наиболее часто возникаю ошибки при сборке PDF. При сборке используется генерация в LaTeX. Стандартные настройки шаблона LaTeX, используемого Read the Docs, не поддерживают кириллицу. Подробнее смотрите раздел Ошибки при сборке PDF на Read The Docs .

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

• git add файлы — добавляет файлы в индекс
• git commit — отправляет из индекса в хранилище для дальнейшей отправки (git push) в удаленный репозиторий
• git reset — файлы заменяет файлы в индексе файлами из последнего коммита
• git checkout файлы — заменяет файлы проекта ни диске файлами из индекса
• git push origin master — отправляет файл на сервер, чтобы не вводить каждый раз логин/пароль, воспользуйтесь флагом ‘-u’

Чтобы создать новую ветку, нужно использовать команду git branch [Название_ветки] . Если написать просто git branch — покажет список существующих веток.

1 способ. Простой, без установки Git.

Переходим по ссылке и жмём «Download ZIP»:

Скачается архив ZIP. Открываем его и распаковываем sh скрипт:

Переходим в каталог куда распаковали скрипт sh. Кликаем правой кнопкой мыши по файлу, открываем «Свойства». В «Свойствах» на вкладке «Права» выставляем флажок «Разрешить выполнение файла как программы»:

Теперь двойным кликом мыши по файлу запускаем sh скрипт:

Для этих скриптов предпочтительнее выбирать вариант запуска: «Запустить в терминале», чтобы видеть вывод служебных сообщений в терминале.

Заключение

Если вы планируете кандидировать на вакансию верстальщика / фронтенд-разработчика в IT компанию, то нужно обязательно уметь работать с GitHub. Поэтому лучший способ показать, что вы с гитхабом на ты – это разместить на GitHub Pages портфолио, а на Gist-е какие-нибудь ваши наработки по верстке и скриптам.

Копирование материалов разрешается только с указанием автора (Михаил Русаков) и индексируемой прямой ссылкой на сайт (http://myrusakov.ru)!

Добавляйтесь ко мне в друзья ВКонтакте: http://vk.com/myrusakov.
Если Вы хотите дать оценку мне и моей работе, то напишите её в моей группе: http://vk.com/rusakovmy.

Если Вы не хотите пропустить новые материалы на сайте,
то Вы можете подписаться на обновления: Подписаться на обновления

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

Порекомендуйте эту статью друзьям:

Если Вам понравился сайт, то разместите ссылку на него (у себя на сайте, на форуме, в контакте):

Она выглядит вот так:

Как загрузить файлы на удаленный репозиторий. Работа с GitHub

Ранее в статьях мы рассматривали как установить, настроить и работать с локальным репозиторием Git. А в этой статье напомним как заливать файлы на удаленный репозиторий и основной функционал и возможности при работе в аккаунте GitHub.

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

Начнем с регистрации на GitHub. Переходим по ссылке https://github.com/ , нажимаем на ‘Sign up’ и проходим регистрацию.

После регистрации перейдем к созданию и настройке репозитория. Кликаем на значок ‘ +’ и в открытом окне выбираем ‘New repository’ для создания нового репозитория.

Заполняем поле и добавляем конфигурации к репозиторию.

Note: Возможность использовать приватный репозиторий бесплатно до 5 соавторов. Далее нужно оплачивать по прайсу в зависимости от тарифного плана.

Также Вы можете поставить галочку напротив “Initialize this repository with a README”, чтобы создать файл readme.md. В файле readme.md зачастую пишут общую ознакомитильную информацию о проекте, требования к окружению, что нужно сделать перед установкой, как установить, создатели проекта, документация, ссылки и много другое. Этот файл оформляется на языке разметки Markdown (ознакомится с синтаксисом языка можно на странице GitHub — https://guides.github.com/features/mastering-markdown/ ).

Перейдем к осмотру как залить файлы в удаленный репозиторий.

Если Вы еще не подключили удаленный репозиторий, то делаем это командой:

где test2 – названия Вашего репозитория,

URL – URL-адрес Вашего репозитория.

Чтобы посмотреть все подключенные репозитории воспользуйтесь командой:

Как видим по скрину репозиторий test2 удачно добавился.

Для подключения можно использовать HTTPS и SSH протоколы. Найти эти поля можно выполнив такие действия: кликаем на иконку с Вашим профилем — Your repositories — и выбираем нужный репозиторий. В открытом окне переходим на ‘Clone or dowland’ и просто копируем ссылку с поля: соответственно либо HTTPS либо SSH доступом. Как Вы поняли по названию, эту ссылку можно использовать и в других целях, например, для клонирования репозитория.

Выбираем нужный протокол, для использования SSH нужно сгенерировать и добавить SSH keys, как это делать можно узнать в нашей статье ‘ Генерация и добавления SSH ключа для подключения к удаленному репозиторию GitHub’.

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

Для этого нужно воспользоваться командой:

Переходим на GitHub и видим, что все наши файлы удачно переместились.

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

Если Вы ведете свой проект на GitHub, значит у Вас есть актуальная текущая версия своего проекта под рукой.Ну конечно же, если дело идет о Хостинге, лучше хранить свои данные не в одном месте и всегда иметь резервные копии. На любом тарифе Хостинга мы делаем бекапы файлов и БД каждый день. С ГиперХост Вы можете быть уверенным, что Ваш проект в надежных руках.