MkDocs

  1. обзор
  2. Хост где угодно
  3. Отличные темы доступны
  4. Предварительный просмотр вашего сайта, как вы работаете
  5. Легко настроить
  6. Монтаж
  7. Ручная установка
  8. Установка Python
  9. Установка пипса
  10. Установка MkDocs
  11. Начиная
  12. Добавление страниц
  13. Тематика нашей документации
  14. Изменение значка Favicon
  15. Создание сайта
  16. Другие команды и параметры
  17. Развертывание
  18. Получать помощь

Проектная документация с уценкой.

обзор

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/ в своем браузере, и вы увидите отображаемую по умолчанию домашнюю страницу:

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.