Mkdocs, vytvářejte dokumentaci díky tomuto open source softwaru

V dalším článku se podíváme na Mkdocs. Pokud vyvíjíte software a hledáte platforma pro vytváření dokumentace pro jeden z vašich projektů. Nebo pokud pracujete ve společnosti, která potřebuje vytvořit interní dokumentaci pro zaměstnance. I když jste pokročilý uživatel, který si chce uložit nějaké poznámky. MkDocs je nástroj, který byste měli vyzkoušet.

Tento software je statický generátor stránek zaměřený na vytváření dokumentačních platforem. Je to docela jednoduché, hezké na pohled a snadné nastavení a nasazení. Je napsáno v pythonu a jednoduše vyžaduje, abyste vytvořili soubory ve formátu Markdown. Potom pomocí jediného konfiguračního souboru YAML můžete vygenerovat statický web, který vám vyhovuje.

Dále uvidíme, jak snadné je získat kompletní dokumentační web pomocí MkDocs. Existuje mnoho dalších generátory webů podobné statické, ale tohle má konfiguraci a implementaci nejjednodušších.

Normální uživatel může tento software také použít k vytvořit místní platformu pro psaní poznámek pro sebe nebo cokoli jiného podobného.

Nainstalujte si MkDocs

Nainstalujte lokálně

Uvidíme, že instalace MkDocs je docela snadná. Budeme moci nainstalujte jej pomocí pip. Musíte otevřít terminál (Ctrl + Alt + T) a napsat do něj:

pip install mkdocs

Po instalaci ve svém pracovním adresáři spusťte následující příkaz na inicializovat web:

mkdocs new mkdocspro

A pak k začněte to sloužit běh:

cd mkdocspro

mkdocs serve

Potom můžeš přejděte na localhost: 8000 (nebo vaše IP adresa / název hostitele s portem 8000) a uvidíte, jak MkDocs funguje.

Nainstalujte si na server nginx

Jelikož se jedná o statický generátor stránek, není potřeba žádný backendový engine jako PHP nebo Python. Projekt MkDocs budete moci implementovat na svém webovém serveru (nginx, apache2) za minutu. Například zde je konfigurace virtuálního hostitele nginx:

server {
        server_name ejemplo.com;

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

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

Nahrazuje example.com s doménou, kterou máte na serveru. Budete také muset změnit / var / www / mkdocspro / web cestou podsložky webu na vašem serveru. Pak máme jen restartujte nginx s následujícím příkazem:

sudo service nginx restart

Nyní můžete přejít na example.com a vidět, že funguje.

Nainstalujte si další motiv do Mkdocs

Výchozí téma Mkdocs není nijak zvlášť dobré. Ale za minutu můžete nainstalovat další. Příklad instalace jiného tématu bude následující. Se kterým se chystáme nainstalujte téma materiálu:

pip install mkdocs-material

Po instalaci budete muset motiv aktivovat upravte svůj soubor mkdocs.yml a vytvořte podobný soubor. Lze přidat některé možnosti:

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'

Možnosti jsou zcela jasné. Zde je ale několik vysvětlení:

• repo_url: je URL úložiště Git. Pokud plánujete integrovat Git přímo do vašeho projektu MkDocs, můžete pomocí této možnosti lidem umožnit úpravy stránek nebo rozvětvení projektu.
• upravit_uri: To je postfix pro úpravy stránek na GitHubu. Můžete to změnit, pokud používáte GitLab nebo GitBucket.
• google_analytics: Pro MkDocs neexistuje žádný ovládací panel. Proto vědět kdo navštíví váš web, musíte použít Google Analytics. Tato možnost vám umožní vložit vaše sledovací číslo a přidružit váš účet k webové stránce.
• diskutovat: Jestli chceš povolit systém komentářů Disqus na webové stránce zde můžete zadat své krátké jméno.
• téma: název motivu, který chcete použít. Budete si ji muset nainstalovat dříve, stejně jako jsme to udělali s tématem materiálu. Toto bude název, který použijeme v příkladu.

Podívejte se na změny nového motivu

Po uložení souboru spusťte mkdocs build uvnitř složky mkdocsproject. Váš web přijme výchozí vzhled motivu Materiál:

Důležité: po každé úpravě vždy spusťte mkdocs build které děláte v souborech. Jinak neuvidíte žádnou změnu.

Existuje mnoho další témata a možnosti konfigurovat tento software. Můžete je konzultovat v oficiální dokumentace podle MkDocs. Zde je seznam možné možnosti které můžeme použít.