MkDocs
- обзор
- Хост где угодно
- Отличные темы доступны
- Предварительный просмотр вашего сайта, как вы работаете
- Легко настроить
- Монтаж
- Ручная установка
- Установка Python
- Установка пипса
- Установка MkDocs
- Начиная
- Добавление страниц
- Тематика нашей документации
- Изменение значка Favicon
- Создание сайта
- Другие команды и параметры
- Развертывание
- Получать помощь
Проектная документация с уценкой.
обзор
MkDocs - это быстрый , простой и просто великолепный генератор статических сайтов, предназначенный для создания проектной документации. Исходные файлы документации написаны на Markdown и настроены с помощью одного файла конфигурации YAML.
Хост где угодно
MkDocs создает полностью статические HTML-сайты, которые вы можете разместить на страницах GitHub, Amazon S3 или в любом месте иначе вы выбираете.
Отличные темы доступны
Для MkDocs есть множество красивых тем. Выберите между встроенными темами: mkdocs а также readthedocs выберите одну из сторонних тем в MkDocs вики , или же Построй свой собственный ,
Предварительный просмотр вашего сайта, как вы работаете
Встроенный dev-сервер позволяет вам просматривать документацию по мере ее написания. Он даже автоматически перезагрузит и обновит ваш браузер, когда вы сохраните изменения.
Легко настроить
Сделайте так, чтобы документация вашего проекта выглядела так, как вы хотите, настроив тему.
Монтаж
Установить с помощью диспетчера пакетов
Если у вас есть и использовать менеджер пакетов (например, APT-получить , д.н.ф. , доморощенного , ням , шоколадным и т. д.) для установки пакетов в вашей системе, затем вы можете выполнить поиск пакета «MkDocs» и, если доступна последняя версия, установить его с помощью диспетчера пакетов (см. подробности в документации по вашей системе). Вот и все, вы сделали! Перейти к Начиная ,
Если у вашего менеджера пакетов нет последнего пакета "MkDocs", вы все равно можете использовать свой менеджер пакетов для установки "Python" и "pip". Тогда вы можете использовать pip для установить MkDocs ,
Ручная установка
Чтобы вручную установить MkDocs, вам понадобится питон установленный в вашей системе, а также менеджер пакетов Python, зернышко , Вы можете проверить, установлены ли они уже из командной строки:
$ python --version Python 2.7.2 $ pip --version pip 1.5.2
MkDocs поддерживает Python версий 2.7, 3.4, 3.5, 3.6, 3.7 и pypy.
Установка Python
устанавливать питон загрузив установщик, соответствующий вашей системе, из python.org и запустить его.
Заметка
Если вы устанавливаете Python в Windows, обязательно установите флажок, чтобы Python добавлялся в PATH, если установщик предлагает такую опцию (обычно она отключена по умолчанию).
Установка пипса
Если вы используете последнюю версию Python, менеджер пакетов Python, зернышко , скорее всего, установлен по умолчанию. Тем не менее, вам может потребоваться обновить pip до последней версии:
pip install --upgrade pip
Если вам нужно установить зернышко впервые скачать get-pip.py , Затем выполните следующую команду, чтобы установить его:
python get-pip.py
Установка MkDocs
Установите пакет mkdocs с помощью pip:
pip install mkdocs
Теперь у вас должна быть установлена команда mkdocs. Запустите mkdocs --version, чтобы убедиться, что все работает нормально.
$ mkdocs - версия mkdocs, версия 0.15.3
Заметка
Если вы хотите, чтобы man-страницы были установлены для MkDocs, нажмите человек Инструмент может сгенерировать и установить их для вас. Просто выполните следующие две команды:
pip install click-man click-man - целевой путь / к / man / pages mkdocs
Увидеть документация по клику для объяснения того, почему страницы не создаются автоматически и не устанавливаются pip.
Заметка
Если вы используете Windows, некоторые из вышеперечисленных команд могут не работать "из коробки".
Быстрое решение может заключаться в том, чтобы предварять каждую команду Python с помощью python -m следующим образом:
python -m pip установить mkdocs python -m mkdocs
Для более постоянного решения вам, возможно, потребуется отредактировать переменную среды PATH, включив в нее каталог Scripts вашей установки Python. Последние версии Python включают скрипт, который сделает это за вас. Перейдите в каталог установки Python (например, C: \ Python34 \), откройте папку «Инструменты», затем «Сценарии» и запустите файл win_add2path.py, дважды щелкнув по нему. Кроме того, вы можете скачать скрипт и запустить его (python win_add2path.py).
Начиная
Начать очень легко.
mkdocs новый my-проект cd my-project
Найдите минутку, чтобы просмотреть первоначальный проект, который был создан для вас.
Существует один файл конфигурации с именем mkdocs.yml и папка с именем docs, которая будет содержать исходные файлы вашей документации. Прямо сейчас папка docs содержит только одну страницу документации с именем index.md.
MkDocs поставляется со встроенным dev-сервером, который позволяет просматривать документацию во время работы над ней. Убедитесь, что вы находитесь в том же каталоге, что и файл конфигурации mkdocs.yml, а затем запустите сервер, выполнив команду mkdocs serve:
$ mkdocs serve INFO - Строительная документация ... INFO - Каталог очистки сайта [I 160402 15:50:43 сервер: 271] Обслуживание на http://127.0.0.1:8000 [I 160402 15:50:43 обработчики: 58] Начните наблюдать изменения [I 160402 15:50:43 обработчики: 60] Начните обнаруживать изменения
Откройте http://127.0.0.1:8000/ в своем браузере, и вы увидите отображаемую по умолчанию домашнюю страницу:
Dev-сервер также поддерживает автоматическую перезагрузку и будет перестраивать вашу документацию всякий раз, когда что-либо в файле конфигурации, каталоге документации или каталоге темы изменяется.
Откройте документ docs / index.md в любом текстовом редакторе, измените исходный заголовок на MkLorum и сохраните изменения. Ваш браузер автоматически перезагрузится, и вы должны увидеть обновленную документацию немедленно.
Теперь попробуйте отредактировать файл конфигурации: mkdocs.yml. Изменить Название сайта установите MkLorum и сохраните файл.
имя_сайта: MkLorum
Ваш браузер должен немедленно перезагрузиться, и вы увидите, как ваше новое имя сайта вступит в силу.
Добавление страниц
Теперь добавьте вторую страницу к вашей документации:
curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt'> docs / about.md
Поскольку наш сайт документации будет содержать некоторые заголовки навигации, вы можете отредактировать файл конфигурации и добавить некоторую информацию о порядке, заголовке и вложенности каждой страницы в заголовок навигации, добавив страницы установка:
имя_сайта: MkLorum nav: - Главная: index.md - О себе: about.md
Сохраните ваши изменения, и теперь вы увидите панель навигации с элементами Home и About слева, а также элементы Search, Previous и Next справа.
Попробуйте пункты меню и перемещайтесь назад и вперед между страницами. Затем нажмите на Поиск. Появится диалоговое окно поиска, позволяющее искать любой текст на любой странице. Обратите внимание, что результаты поиска включают каждое вхождение поискового термина на сайте и ссылки непосредственно на раздел страницы, в которой появляется поисковый термин. Вы получаете все это без усилий или настроек с вашей стороны!
Тематика нашей документации
Теперь измените файл конфигурации, чтобы изменить способ отображения документации путем изменения темы. Отредактируйте файл mkdocs.yml и добавьте тема установка:
имя_сайта: MkLorum nav: - Дом: index.md - О себе: about.md тема: readthedocs
Сохраните ваши изменения, и вы увидите используемую тему ReadTheDocs.
Изменение значка Favicon
По умолчанию MkDocs использует MkDocs favicon значок. Чтобы использовать другой значок, создайте подкаталог img в вашем docs_dir и скопируйте в него этот пользовательский файл favicon.ico. MkDocs автоматически обнаружит и использует этот файл в качестве значка избранного.
Создание сайта
Это выглядит хорошо. Вы готовы развернуть первый проход вашей документации MkLorum. Сначала соберите документацию:
сборка mkdocs
Это создаст новый каталог с именем site. Загляните в каталог:
$ ls сайт о шрифтах index.html лицензия search.html css img js mkdocs sitemap.xml
Обратите внимание, что исходная документация была выведена в виде двух файлов HTML с именами index.html и about / index.html. У вас также есть различные другие носители, которые были скопированы в каталог сайта как часть темы документации. У вас даже есть файл sitemap.xml и mkdocs / search_index.json.
Если вы используете контроль исходного кода, такой как git, вы, вероятно, не хотите проверять сборки документации в репозитории. Добавьте строку, содержащую сайт /, в ваш файл .gitignore.
echo "site /" >> .gitignore
Если вы используете другой инструмент управления исходным кодом, вы можете проверить его документацию о том, как игнорировать определенные каталоги.
Через некоторое время файлы могут быть удалены из документации, но они все равно будут находиться в каталоге сайта. Чтобы удалить эти устаревшие файлы, просто запустите mkdocs с ключом --clean.
mkdocs build --clean
Другие команды и параметры
Существуют различные другие доступные команды и опции. Для полного списка команд используйте флаг --help:
mkdocs --help
Чтобы просмотреть список параметров, доступных для данной команды, используйте флаг --help с этой командой. Например, чтобы получить список всех параметров, доступных для команды построения, выполните следующее:
mkdocs build --help
Развертывание
Сайт документации, который вы только что создали, использует только статические файлы, поэтому вы сможете разместить его практически из любого места. Страницы проекта GitHub а также Amazon S3 может быть хорошим вариантом хостинга, в зависимости от ваших потребностей. Загрузите содержимое всего каталога сайта туда, где вы размещаете свой сайт, и все готово. Конкретные инструкции по ряду общих хостов см. В Развертывание ваших документов стр.
Получать помощь
Чтобы получить помощь по MkDocs, пожалуйста, используйте дискуссионная группа , GitHub вопросы или IRC-канал MkDocs #mkdocs на freenode.