В этой инструкции собраны советы и подсказки для желающих сделать вклад в книгу "Где сохранить пакет".
Readthedocs - это платформа, которая позволяет отображать репозиторий GitHub в виде книги. Вёрстка ведётся в синтаксисе ReStructured Text.
Для генерации книги из набора файлов *.rst изспользуется Sphinx.
Исходники статьи хранятся в каталоге docs/source.
Сгенерированные html - в docs/build.
То, что отображается в левой колонке со структурой документа (Содежрание), задаётся в файле docs/contents.rst.
Желательно содержимое файла docs/index.rst сохранять таким же, как и docs/contents.rst.
Познакомимся с Git. Опытные пользователи могут пропустить этот раздел.
-
Для начала установите Git.
В Debian/Ubuntu в командной строке необходимо выполнить:
sudo apt-get install git
В Fedora:
yum install git-core
В случае другой *nix системы, предполагается что пользователь знает как устанавливать приложения из пакетов, исходников или любым другим способом.
В macOS можно воспользоваться графическим инсталлятором, либо установить через MacPorts. Если он уже установлен, в консоли необходимо выполнить команду:
sudo port install git-core +doc +bash_completion +gitweb
Для Windows необходимо скачать exe-файл инсталлятора со страницы проекта на GitHub'е и запустить его. После установки будет доступна как консольная, так и графическая версии Git. -
Затем зарегистрируйтесь или вспомните свои логин и пароль на github.com.
-
Создайте fork проекта where-to-store-the-packet. Для этого нужно зайти на страницу проекта и нажать в правом верхнем углу кнопку "Fork".
-
Склонируйте репозиторий. Для редактирования в текстовом редакторе нужно сделать локальную копию репозитория. Для этого необходимо создать и перейди в папку, где будет размещаться проект и склонировать репозиторий.
В *nix:
git clone URL
В этом случае копия репозитория будет сохранена в каталог "where-to-store-the-packet" в домашней папке пользователя, либо можно указать путь прямо в команде:
В Windows всё делается аналогично, только мышкой в GitHub Desktop. -
Редактируйте!
Вы можете вносить изменения в проект с помощью любого удобного инструмента: -
Сбилдите книгу. Когда вы закончили редактирование, запустите
make htmlиз каталогаdocs. Это соберёт build из source. В ходе билда могут появиться ошибки - внимательно читайте их.
Предварительно вам нужно установить генератор python-документации Sphinx. -
После внесения изменений нужно закоммитить их в свой репозиторий (fork оригинального проекта).
В *nix:
git add .- добавить изменённые файлы, подробнее.
git commit- закоммитить изменения в репозиторий, либо сразу с комментарием:
git commit -m "что, где и зачем было сделано"
git push origin master- push в master ветку своего репозитория.
Подробнее оgit push, ветках и т.п. Ну и в целом, рекомендуется хотя бы пролистать инструкцию или пройти небольшой интерактивный курс - раз, два.
В Windows всё примерно так же. -
Чтобы изменения стали общественным достоянием, а не пылились в вашем форке, нужно создать pull request в оригинальный репозиторий where-to-store-the-packet. Сделать это можно разными способами, для простоты лучше зайти на страницу своего репозитория на GitHub, выбрать New pull request, в качестве источника выбрать ветку в своём репозитории (если вы не делали лишних движений, то ветка будет одна и это master), в качестве получателя - master проекта eucariot/where-to-store-the-packet.
Проверить вносимые изменения, подтвердить создание pull request.
В качестве комментария указать какие изменения были внесены, желательно писать человекопонятные комментарии, подробнее.
Рекомендуется коммитить и создавать pull request каждый раз, когда выполнена логически завершенная часть изменений (например, изменения в конкретной статье или изменения, затрагивающие однотипные действия, например исправление ссылок).
Важно: делайте git pull каждый раз перед началом работы. Иначе можно словить merge конфликт, когда один и тот же документ правили двое и долго этот конфликт разрешать. Соответственно pull request тоже лучше делать почаще.
docs/contents.rst - формирует Содержание книги (левая колонка) и соответственно страницу contents.html
docs/index.rst - формирует то, что будет отображаться на главной странице. Логично делать его содержимое одинаковым с contents.rst
Каждая глава книги нумеруется. Если содержимое небольшое, то глава полностью сохраняется в виде одного файла номер_название.rst. Если глава большая, то под неё созаётся каталог номер_название с несколькими файлами, которые тоже нумеруются и именуются.
Для того, что бы файл появился в содержании и вообще в книге, на него должна быть явно дана ссылка, например, с помощью конструкции .. toctree:: (примеры ищите в коде книги).
Общие рекомендации:
- Следите за орфографией и пунктуацией, используйте плагин Spell Check в вашем любимом редакторе или проверяйте получившийся текст в Word, только без маниакальности;
- Использование буквы "ё" приветствуется;
- Не забывайте про знаки препинания и пробелы (или их отсутствие) вокруг них, корректное оформление улучшает читаемость;
- Придерживайтесь одного стиля изложения;
- Сохраняйте терминологию и формулировки хотя бы в рамках одной статьи (роутер, рутер, маршрутизатор). Не используйте перевод или транслитерацию терминов, названий фирм, сервисов и пр. Очевидно есть исключения для слов, вошедших в повседневное и повсеместное употребление.
- При использовании сокращений и аббревиатур, укажите термин в полном виде при первом упоминании в статье;
- Избегайте формулировок, допускающих толкование.
- Помните про авторские права при размещении изображений, видео и других материалов, найденных на просторах интернета.
- Используйте заголовки не более двух уровней вложенности. Если их больше, значит это повод задуматься о разбиении статьи на разделы или подразделы;
- Помещайте код, листинги и результаты выполнения команд в блок
.. code-block::(например,.. code-block:: python);