Предисловие
В последнее время в русскоязычном сегменте интернета все реже и реже попадаются толковые статьи. Особенно это касается статей на техническую тему. Многие из них лишь поверхностно касаются озвученных вопросов, даже не предоставляя никаких ссылок на дополнительную информацию.
С целью хоть чуточку изменить ситуацию в лучшую сторону, я решил задокументировать свой опыт в виде монолитного руководства. Конечно, рассмотреть абсолютно все аспекты не представляется возможным. Поэтому такие места снабжены ссылками на другие источники.
Несмотря на благие намерения, данное руководство можно улучшить и дополнить. Критика, замечания и предложения приветствуются. Также буду рад любому сотрудничеству. Пишите мне на почту (см. Обратная связь) или отправляйте Pull Requests (см. Pull Requests).
О чём данное руководство?
Данное руководство посвящено процессу генерации документации с помощью связки reStructuredText, Python Sphinx, GitHub и сервиса Read the Docs. Ключевую роль в этой связке играет генератор документации Python Sphinx, разработанный для документирования языка программирования Python, но активно прижившегося и в других проектах.
Sphinx использует облегченный язык разметки reStructuredText, с помощью которого можно создавать текстовые документы с четкой структурой. В дальнейшем, такие документы могут быть преобразованы в любой другой формат: HTML, LaTeX, ODT, ePub, man и другие. Sphinx расширяет возможности reStructuredText и упрощает процесс генерации в различные форматы.
GitHub позволяет организовать совместную работу над документацией и значительно упрощает процесс отслеживания изменений. Сервис Read the Docs предоставляет бесплатную площадку для публикации документации, сгенерированной с помощью Sphinx. Он автоматизирует процесс создания и загрузки Sphinx-документации после каждой фиксации изменений на GitHub.
Почему именно Sphinx?
На данный момент я состою в русскоязычном сообществе LibreOffice и курирую работу над написанием и оформлением официальной русскоязычной документации по офисному пакету. У меня большой опыт работы со сложными документами. Я занимался версткой документов и с помощью обычных офисных пакетов, и с помощью LaTeX.
Офисные пакеты хорошо справляются со сложной документацией, они достаточно просты для обычных пользователей, но очень плохо приспособлены для совместной работы. Конечно, LibreOffice имеет встроенные функции контроля версий документов, записи изменений, имеется отличная функция «Составные документы», которая позволяет обеспечить одновременную совместную работу над сложными документами. Но все это не даёт той гибкости, которая есть у систем управления версиями файлов таких, как, например, Git.
LaTeX лишен многих недостатков офисных пакетов, обладает потрясающим качеством генерации документов, но имеет высокий входной порог. Последнее обстоятельство затрудняет совместную работу и во многом перекладывает значительную часть работы на плечи редактора.
Sphinx совмещает в себе качество LaTeX и простоту офисных пакетов. Для совместной работы достаточно иметь обыкновенный текстовый редактор, что освобождает от привязки к каким-либо платформам, избавляет от установки громоздких программ и значительно упрощает работу редактора по оформлению и генерации документации.
В связке Sphinx с GitHub и Read the Docs упрощается процесс отслеживания изменений в документации и её публикация.
Структура книги
В главе «Генератор документации Sphinx» описана установка и основные настройки Sphinx.
В главе «Стандартный синтаксис разметки reStructuredText» приведен стандартный синтаксис разметки reStructuredText. Глава «Конструкции разметки Sphinx» содержит описание дополнительных конструкции разметки, вносимых Sphinx. Данные конструкции значительно расширяют функционал reStructuredText, но не поддерживаются стандартной разметкой и поэтому не могут быть применены вне Sphinx.
Глава «Система управления версиями Git» является справочником по основным командам git.
Глава «GitHub и Read The Docs» рассматривает веб-сервис для хостинга IT-проектов GitHub, сервис Read The Docs и их взаимодействие.
В главах «Известные проблемы» и «Часто задаваемые вопросы» описаны основные проблемы, с которыми я столкнулся.
Рекомендации
Отдельным авторам и переводчикам документации для работы не нужно иметь установленный Sphinx, а , следовательно, нет необходимости читать многие разделы данного руководства. Им достаточно прочитать раздел Стандартный синтаксис разметки reStructuredText и Конструкции разметки Sphinx, чтобы изучить необходимый синтаксис. А также ознакомиться с разделом Работа с GitHub. Этого минимума хватит для комфортной работы как самих авторов/переводчиков, так и редакторов.
Редакторы, для облегчения своей работы, должны дать авторам и переводчикам рекомендации относительно оформления исходного текста, создания закладок и указателей. В качестве примера смотрите раздел Соглашения.
Авторские права
Руководство распространяется на условиях лицензии «Attribution-ShareAlike» («Атрибуция — На тех же условиях») 4.0 Всемирная (CC BY-SA 4.0) 1.
Дата публикации и версия программного обеспечения
Опубликовано 29 декабря 2014 года. При написании руководства были использованы:
Программа |
Версия |
|---|---|
Sphinx |
1.2.2 |
Git |
2.1.0 |
Обратная связь
- Автор
Дмитрий Мажарцев
- Контакты
- Блог
- Адрес
Волгоград
- Дата
29 декабря 2014 года