Mkdocs, создавайте документацию благодаря этому ПО с открытым исходным кодом

В следующей статье мы рассмотрим Mkdocs. Если вы разрабатываете программное обеспечение и ищете платформа для создания документации для одного из ваших проектов. Или если вы работаете в компании, которой необходимо создать внутреннюю документацию для персонала. Даже если вы опытный пользователь, который хочет сохранить заметки. MkDocs - это инструмент, который вам стоит попробовать.

Это программное обеспечение представляет собой генератор статических сайтов, предназначенный для создания платформ документации. Это довольно просто, красиво и легко настроить и развернуть. Является написано на питоне и просто требует, чтобы вы создавали файлы в формате Markdown. Затем, используя один файл конфигурации YAML, вы можете создать статический веб-сайт, который будет работать на вас.

Далее мы увидим, насколько легко получить веб-сайт с полной документацией с помощью MkDocs. Есть много других генераторы сайтов аналогичная статика, но это имеет конфигурацию и реализацию простейшего.

Обычный пользователь также может использовать это программное обеспечение для создать локальную платформу для заметок для себя или что-нибудь подобное.

Установить MkDocs

Установить локально

Давайте посмотрим, что установить MkDocs довольно просто. Мы сможем установить его с помощью пипса. Вам просто нужно открыть терминал (Ctrl + Alt + T) и написать в нем:

pip install mkdocs

После установки в вашем рабочем каталоге выполните следующую команду, чтобы инициализировать сайт:

mkdocs new mkdocspro

А потом начни подавать это бежать:

cd mkdocspro

mkdocs serve

Тогда ты можешь перейти на localhost: 8000 (или ваш IP-адрес / имя хоста с портом 8000), чтобы увидеть, как работает MkDocs.

Установите на свой сервер nginx

Поскольку это генератор статических сайтов, не требуется никакого внутреннего движка, такого как PHP или Python. Вы сможете реализовать проект MkDocs на своем веб-сервере (nginx, apache2) за минуту. Например, вот конфигурация виртуального хоста nginx:

server {
        server_name ejemplo.com;

        root /var/www/mkdocspro/sitio;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

Заменяет ejemplo.com с доменом, который у вас есть на вашем сервере. Вам также придется изменить / вар / www / mkdocspro / сайт по пути к подпапке сайта на вашем сервере. Тогда у нас есть только перезапустить nginx с помощью следующей команды:

sudo service nginx restart

Теперь вы можете зайти на example.com и посмотреть, как это работает.

Установите другую тему в Mkdocs

Тема Mkdocs по умолчанию не особенно хороша. Но вы можете установить еще одну за минуту. Пример установки другой темы будет следующий. С чем мы собираемся установить тему материала:

pip install mkdocs-material

После установки для активации темы вам потребуется отредактируйте файл mkdocs.yml и сделайте его похожим на этот. Могут быть добавлены некоторые опции:

site_name: Proyecto MkDocs
site_url: 'http://ejemplo.com'
repo_url: 'https://github.com/nombreusuario/proyectourlongithub'
edit_uri: edit/master
site_description: 'Aquí una descripción corta.'
google_analytics: ['UA-xxxxxxxxx-x', 'ejemplo.com']
extra:
  favicon: 'https://ejemplo/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'minombredisqus'
  theme: 'material'

Варианты вполне понятны. Но вот некоторые объяснения:

• repo_url: это URL-адрес репозитория Git. Если вы планируете интегрировать Git непосредственно в свой проект MkDocs, вы можете использовать эту опцию, чтобы позволить людям редактировать страницы или создавать ветвь проекта.
• edit_uriЭто постфикс для редактирования страниц на GitHub. Вы можете изменить его, если используете GitLab или GitBucket.
• google_analytics: Нет панели управления для MkDocs. Следовательно, чтобы знать кто посещает ваш сайт, вы должны использовать Google Analytics. Эта опция позволит вам вставить свой номер отслеживания, чтобы связать вашу учетную запись с веб-сайтом.
• Disqus: Если хочешь включить систему комментирования Disqus на сайте вы можете вставить здесь свое короткое имя.
• тема: The название темы, которую вы хотите использовать. Вам нужно будет установить его заранее, как мы только что сделали с темой материала. Это будет имя, которое мы будем использовать в примере.

Смотрите изменения новой темы

После сохранения файла запустите сборку mkdocs внутри папки mkdocsproject. Ваш веб-сайт примет внешний вид темы Material по умолчанию:

Внимание: обязательно запускайте сборку mkdocs после каждой модификации что вы делаете в файлах. В противном случае вы не увидите никаких изменений.

Есть много другие темы и опции для настройки этого программного обеспечения. Вы можете проконсультироваться с ними в официальная документация пользователя MkDocs. Вот список возможные варианты что мы можем использовать.