Mkdocs, készítsen dokumentációt ennek a nyílt forráskódú szoftvernek köszönhetően

A következő cikkben megnézzük az Mkdocs-t. Ha szoftvert fejleszt és keres platform a dokumentáció készítéséhez az egyik projektjéhez. Vagy ha olyan cégben dolgozik, amelynek belső dokumentációt kell készítenie a személyzet számára. Még akkor is, ha haladó felhasználó vagy, és el akarsz menteni néhány jegyzetet. Az MkDocs egy olyan eszköz, amelyet érdemes kipróbálni.

Ez a szoftver egy statikus webhelygenerátor, amelynek célja a dokumentációs platformok létrehozása. Elég egyszerű, megnézhető, és könnyen beállítható és telepíthető. Is pythonban írva és egyszerűen megköveteli, hogy a fájlokat Markdown formátumban hozza létre. Ezután egyetlen YAML konfigurációs fájl segítségével létrehozhat egy statikus webhelyet, amely az Ön számára megfelelő.

Ezután meglátjuk, mennyire egyszerű egy teljes dokumentációs weboldalt beszerezni az MkDocs segítségével. Sok más van webhelygenerátorok hasonló statikus, de ez konfigurációja és megvalósítása a legegyszerűbb.

Egy normál felhasználó is használhatja ezt a szoftvert hozzon létre egy helyi platformot a jegyzeteléshez önmagának vagy bármi másnak.

Telepítse az MkDocs alkalmazást

Telepítés helyben

Lássuk, hogy az MkDocs telepítése meglehetősen egyszerű. Meg tudjuk telepítse a pip használatával. Csak meg kell nyitnia egy terminált (Ctrl + Alt + T), és be kell írnia:

pip install mkdocs

A telepítés után a munkakönyvtárban futtassa a következő parancsot: inicializálja a webhelyet:

mkdocs new mkdocspro

És aztán kezdje el tálalni fuss:

cd mkdocspro

mkdocs serve

Akkor lehet megy a localhost-ra: 8000 (vagy az Ön IP-címe / hosztneve a 8000-es porttal), hogy lássa, hogyan működik az MkDocs.

Telepítse az nginx szerverre

Mivel ez egy statikus helygenerátor, nincs szükség háttérprogram motorra, mint például a PHP vagy a Python. Egy perc alatt képes lesz megvalósítani az MkDocs projektet a webkiszolgálón (nginx, apache2). Például itt van a nginx virtuális gazdagép konfigurációja:

server {
        server_name ejemplo.com;

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

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

Helyettesíti ejemplo.com a szerveren lévő domainnel. Neked is változtatnod kell / var / www / mkdocspro / site a webhely almappájának elérési útján a szerveren. Akkor csak nekünk van indítsa újra a nginx-et a következő paranccsal:

sudo service nginx restart

Most áttérhet az example.com oldalra, és láthatja, hogy működik.

Telepítsen egy másik témát az Mkdocs fájlba

Az alapértelmezett Mkdocs téma nem különösebben jó. De egy perc alatt telepíthet még egyet. Egy másik téma telepítésének példája a következő lesz. Amellyel megyünk anyagtéma telepítése:

pip install mkdocs-material

A telepítés után a téma aktiválásához meg kell szerkessze az mkdocs.yml fájlt, és tegye hasonlóvá. Néhány lehetőség hozzáadható:

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'

A lehetőségek teljesen egyértelműek. De itt van néhány magyarázat:

• repo_url: az a Git-tár URL-je. Ha azt tervezi, hogy közvetlenül integrálja a Git-et az MkDocs-projektjébe, használhatja ezt a lehetőséget, hogy az emberek szerkeszthessék az oldalakat vagy elágazhassanak a projekten.
• edit_uri: Ez a postfix az oldalak szerkesztéséhez a GitHubon. Megváltoztathatja, ha GitLab vagy GitBucket szoftvert használ.
• google_analytics: Nincs vezérlőpult az MkDocs számára. Ezért tudni aki meglátogatja az Ön webhelyét, akkor a Google Analytics szolgáltatást kell használnia. Ez az opció lehetővé teszi, hogy beszúrja a követési számot, hogy társítsa fiókját a webhelyhez.
• Disqus: Ha akarod engedélyezze a Disqus kommentelő rendszert a weboldalon ide írhatja be rövid nevét.
• téma: A a használni kívánt téma neve. Korábban telepítenie kell, ahogy az anyagi témához is tettük. Ezt a nevet fogjuk használni a példában.

Tekintse meg az új téma változásait

A fájl mentése után futtassa az mkdocs buildet az mkdocsproject mappában. Webhelye elfogadja az Anyag téma alapértelmezett megjelenését:

Fontos: minden módosítás után mindig futtassa az mkdocs build fájlt amit a fájlokban tesz. Ellenkező esetben nem lát semmilyen változást.

sok egyéb témák és opciók a szoftver konfigurálásához. Konzultálhat velük a hivatalos dokumentáció írta: MkDocs. Itt van egy lista lehetséges opciók hogy használhatjuk.