Как внести правки в документацию

1. Сделать форк репозитория bigartm/bigartm в своей репозиторий (кнопкой fork на главной страничке библиотеки в гитхабе)

2. Из терминала на своём компьютере клонировать репозиторий:

git clone https://github.com/username/bigartm.git

3. Создать на основе мастера свою ветку (в терминале, находясь в директории bigartm, которая появилась после клонирования)

git checkout master git checkout -b Docs

Docs - это имя новой ветки для работы

Сразу тут же рекомендую настроить remote. Имя origin уже связано с твоей удалённой копией, теперь свяжи ещё имя upstream с основным репозиторием:

git remote add upstream https://github.com/bigartm/bigartm.git

4. Дальше можно вносить правки. Директория docs идейно она устроена так: на каждом уровне документации находится файл index.txt, который описывает содержимое страницы текущего уровня, и от него отходят подстраницы, в которых тоже может быть свой index.txt и т.д. Примеры разметки можно посмотреть в файлах в той же директории, там всего достаточно и не очень сложно. Есть такая документация: http://www.sphinx-doc.org/en/stable/rest.html

5. Когда часть написана, можно проверить, сделав в директории docs

make html

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

6. Если всё готово и протестировано, можно делать коммит и pull-request:

git add --all git commit -m 'some comment' git push origin Docs

Этим Вы отправляете изменения в свою удалённую копию репозитория.

7. Теперь заходите на свой гитхаб, там будет кнопка Compare and Pull Request для Вашего изменения. Нажимаете и создаете реквест.

8. В последнем пункте важно, чтобы изменение было Able to merge. Если вдруг нет, то надо скачать и переместить изменения из основного репозитория (предположим, Вы в своей ветке Docs):

git fetch upstream git rebase upstream/master git push origin Docs -f

-f == --force - значит затереть старую историю коммитов в удалённой копии репозитория и заменить её на отправляемую локальную.