Тот случай, когда для работы над одним руководством, приходится писать другое.
В руководстве подробно описан процесс генерации документации с помощью связки reStructuredText, Python Sphinx, GitHub и сервиса Read the Docs.
Доступно в трёх форматах — онлайн, HTML и ePub.
Структура руководства
В главе «Генератор документации Sphinx» описана установка и основные настройки Sphinx.
В главе «Стандартный синтаксис разметки reStructuredText» приведен стандартный синтаксис разметки reStructuredText. Глава «Конструкции разметки Sphinx» содержит описание дополнительных конструкции разметки, вносимых Sphinx. Данные конструкции значительно расширяют функционал reStructuredText, но не поддерживаются стандартной разметкой и поэтому не могут быть применены вне Sphinx.
Глава «Система управления версиями Git» является справочником по основным командам Git.
Глава «GitHub и Read The Docs» рассматривает веб-сервис для хостинга IT-проектов GitHub, сервис Read The Docs и их взаимодействие.
В главах «Известные проблемы» и «Часто задаваемые вопросы» описаны основные проблемы, с которыми я столкнулся.
Авторские права
Руководство распространяется на условиях лицензии «Attribution-ShareAlike» («Атрибуция — На тех же условиях») 4.0 Всемирная (CC BY-SA 4.0).
Содержание
- Предисловие
- О чём данное руководство?
- Почему именно Sphinx?
- Структура книги
- Рекомендации
- Авторские права
- Дата публикации и версия программного обеспечения
- Обратная связь
- Русскоязычное сообщество LibreOffice
- Новости
- Поддержка
- Обучение
- Независимые блоги
- Списки почтовой рассылки LibreOffice
- Генератор документации Sphinx
- Быстрый старт
- Установка
- Создание нового проекта
- Файл index
- Генерация документа
- Добавление иллюстраций
- Автоматическая сборка (генерация)
- Файл конфигурации
- Общие настройки
- Изменение названия и копирайта
- Строки Unicode
- Версии публикации
- Настройка локализации
- Настройка отображения даты
- Подключение расширений
- Режим отображения формул
- Генерация в формат HTML
- Добавление favicon
- Метаданные. Тег META
- Смена HTML-темы
- Генерация в формат LaTeX
- Преамбула
- Язык и кодировка
- Уровни заголовков в содержании
- Генерация в формат ePub
- Настройка языка
- Отключение копирайта
- Отключение надписи “Created using Sphinx”
- Настройка отображения URL-адресов
- Настройка глубины содержания
- Настройка названия и заголовка
- Быстрый старт
- Стандартный синтаксис разметки reStructuredText
- Что такое reStructuredText?
- Редакторы reStructuredText
- ReText
- Online reStructuredText editor
- NoTex.ch
- rstext.me
- Синтаксис reStructuredText
- Базовые концепции
- Абзацы
- Заголовки
- Начертание
- Нумерованные списки
- Маркированные списки
- Вложенные списки
- Верхний и нижние индексы
- Определения
- Цитаты
- Эпиграф
- Сноски
- Комментарии
- Листинги (исходный код)
- Автозамены (Подстановки)
- Использование символов юникод (unicode)
- Дата и время
- Вставка текста из других файлов
- Черта
- Ссылки
- Изображения и иллюстрации
- Таблицы
- Формулы
- Блоки примечаний и предупреждений
- Содержание
- Метаданные. Тег META
- Конструкции разметки Sphinx
- Автоматическое содержание
- Примеры исходного кода с подсветкой синтаксиса
- Вставка примеров кода из файла
- Вставка формул
- Нумерация формул
- Отображение формул
- Вставка графиков
- Перекрестные ссылки
- Ссылки на разделы
- Ссылки на изображения
- Ссылки на таблицы
- Ссылки на формулы
- Дополнительные конструкции
- Глоссарий
- Аббревиатуры
- Пункты меню
- Автозамены Sphinx (Подстановки)
- Смотрите также
- Рубрики
- Горизонтальный список
- Документация по языкам программирования
- Указатель
- Система управления версиями Git
- Установка Git
- Установка в Ubuntu
- Установка в Fedora
- Установка в OpenSUSE
- Установка в Mac с помощью графического инсталятора Git
- Установка в Mac с помощью MacPorts
- Установка в Windows
- Первичная настройка
- Установка имени и электронной почты
- Параметры установки окончаний строк
- Выбор редактора
- Утилита сравнения
- Просмотр настроек
- Псевдонимы в Git
- Основные команды
- Получение справки
- Создание репозитория в существующем каталоге
- Клонирование существующего репозитория
- Определение состояния файлов
- Отслеживание новых файлов
- Игнорирование файлов
- Просмотр индексированных и неиндексированных изменений
- Фиксация изменений
- Игнорирование индексации
- Удаление файлов
- Перемещение файлов
- Просмотр истории коммитов
- Изменение последнего коммита
- Отмена индексации файла
- Отмена изменений файла
- Просмотр меток (тегов)
- Создание легковесных меток(тегов)
- Создание аннотированных меток(тегов)
- Выставление меток(тегов) позже
- Обмен метками(тегами)
- Удаление меток(тегов)
- Отображение удалённых репозиториев
- Добавление удалённых репозиториев
- Извлечение данных из удаленного репозитория
- Отправка данных в удаленный репозиторий
- Инспекция удалённого репозитория
- Удаление и переименование удалённых репозиториев
- Создание новой ветки
- Переход на другую ветку
- Слияние веток
- Удаление ветки
- Состояние веток
- Перемещение изменений между ветками
- Отслеживание веток
- Удаление веток на удалённом сервере
- Прятанье
- Установка Git
- GitHub и Read The Docs
- Работа с GitHub
- Что такое GitHub
- Регистрация
- Создание репозитория
- Копирование репозитория (Fork)
- Pull Requests
- Ветвление
- Обход блокировки GitHub
- GitHub и совместная работа над документацией
- Работа с Read The Docs
- Регистрация
- Привязка к GitHub
- Создание проекта
- Импорт проекта
- Автоматическая публикация
- Настройка
- Несколько версий документации
- Ошибки сборки
- Работа с GitHub
- Известные проблемы
- Кириллические символы в алфавитном указателе
- Перекрестные ссылки в LaTeX
- Масштабирование изображений в LaTeX
- Ошибки при сборке PDF на Read The Docs
- Некорректно отображаются формулы на Read The Docs
- Ошибки при сборке PDF на Read The Docs
- Часто задаваемые вопросы
- Как добавить подпись к рисунку?
- Как добавить подпись к таблице?
- Как сделать ссылку на главу или раздел?
- Как вставить содержание в разделе (документе)?
- Как сделать перекрестную ссылку на таблицу или рисунок?
- Как сделать перекрестную ссылку в виде категории?
- Вставка графиков
- Как настроить автоматическую генерацию документации
- Соглашения
Комментариев нет:
Отправить комментарий