Mkdocs, looge tänu sellele avatud lähtekoodiga tarkvarale dokumentatsioon

Järgmises artiklis heidame pilgu Mkdocsile. Kui arendate tarkvara ja otsite platvorm dokumentatsiooni loomiseks ühe oma projekti jaoks. Või kui töötate ettevõttes, mis peab personali jaoks looma sisemise dokumentatsiooni. Isegi kui olete kogenud kasutaja, kes soovib mõned märkmed salvestada. MkDocs on tööriist, mida peaksite proovima.

See tarkvara on staatiline saidigeneraator, mille eesmärk on luua dokumentatsiooniplatvorme. See on üsna lihtne, ilus vaadata ja lihtne seadistada ja juurutada. On kirjutatud pythonis ja lihtsalt nõuab failide loomist Markdowni vormingus. Seejärel saate ühe YAML-i konfiguratsioonifaili abil luua staatilise veebisaidi, mis teile sobib.

Järgmisena näeme, kui lihtne on täieliku dokumentatsiooni veebisaidi hankimine MkDocsiga. Neid on veel palju saidi generaatorid sarnane staatiline, kuid see on kõige lihtsama konfiguratsiooni ja rakendusega.

Tavaline kasutaja saaks seda tarkvara kasutada ka selleks looge kohalik platvorm märkmete tegemiseks enda või millegi muu sarnase jaoks.

Installige MkDocs

Paigaldage kohapeal

Vaatame, et MkDocs-i installimine on üsna lihtne. Me saame installige see pipi abil. Peate lihtsalt avama terminali (Ctrl + Alt + T) ja sinna kirjutama:

pip install mkdocs

Pärast installimist käivitage oma töökataloogis järgmine käsk lähtestage sait:

mkdocs new mkdocspro

Ja siis selleks hakka seda serveerima joosta:

cd mkdocspro

mkdocs serve

Siis saab mine kohalikule hostile: 8000 (või teie IP-aadress / hosti nimi koos pordiga 8000), et näha, kuidas MkDocs töötab.

Installige oma nginxi serverisse

Kuna tegemist on staatilise saidigeneraatoriga, pole vaja taustaprogrammi mootorit nagu PHP või Python. MkDocs projekti saate oma veebiserverisse (nginx, apache2) juurutada minutiga. Näiteks siin on nginx virtuaalse hosti konfiguratsioon:

server {
        server_name ejemplo.com;

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

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

Asendab example.com serveris oleva domeeniga. Peate ka muutma / var / www / mkdocspro / site serveri saidi alamkausta tee järgi. Siis on meil ainult taaskäivitage nginx järgmise käsuga:

sudo service nginx restart

Nüüd saate minna saidile example.com ja vaadata, kuidas see töötab.

Paigaldage Mkdocsisse veel üks teema

Mkdocside vaiketeema pole eriti hea. Kuid saate ühe teise installida minuti jooksul. Järgmise teema paigaldamise näide on järgmine. Millega me läheme materjali teema installimine:

pip install mkdocs-material

Pärast installimist peate teema aktiveerimiseks seda tegema muutke faili mkdocs.yml ja muutke see sarnaseks. Mõned valikud saab lisada:

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'

Valikud on üsna selged. Kuid siin on mõned selgitused:

• repo_url: on Giti hoidla URL. Kui kavatsete integreerida Giti otse oma MkDocs'i projekti, saate selle suvandi abil lubada inimestel lehti muuta või projekti hargneda.
• edit_uri: See on postfix GitHubi lehtede muutmiseks. Saate seda muuta, kui kasutate GitLabi või GitBucketit.
• google_analytics: MkDocsil pole juhtpaneeli. Seega teadma kes teie veebisaiti külastab, peate kasutama Google Analyticsi. See valik võimaldab teil sisestada oma jälgimisnumbri, et oma konto veebisaidiga siduda.
• disqus: Kui sa tahad lubage Disquse kommenteerimissüsteem veebisaidil saate siia lisada oma lühikese nime.
• teema: kasutatava teema nimi. Peate selle varem installima, nagu me just materjali teemaga tegime. See on nimi, mida näites kasutame.

Vaadake uue teema muudatusi

Pärast faili salvestamist käivitage mkdocs build mkdocsproject kausta sees. Teie veebisait võtab Materjali teema vaikimisi ilme:

NB! käivitage mkdocs build alati pärast iga muudatust mida te failides teete. Vastasel juhul ei näe te muudatusi.

on palju muud teemad ja valikud selle tarkvara konfigureerimiseks. Nendega saate tutvuda ametlik dokumentatsioon autor MkDocs. Siin on nimekiri võimalikke valikuid mida saame kasutada.