Mkdocs, krijoni dokumentacion falë këtij programi me burim të hapur

Në artikullin vijues do të hedhim një vështrim në Mkdocs. Nëse zhvilloni softuer dhe kërkoni një platformë për krijimin e dokumentacionit për një nga projektet tuaja. Ose nëse punoni në një kompani që duhet të krijojë dokumentacion të brendshëm për stafin. Edhe nëse jeni një përdorues i përparuar që dëshironi të ruani disa shënime. MkDocs është një mjet që duhet ta provoni.

Ky program është një gjenerator statik i faqes që synon krijimin e platformave të dokumentacionit. Prettyshtë shumë e thjeshtë, e bukur për tu parë dhe e lehtë për tu vendosur dhe vendosur. Është shkruar ne python dhe thjesht kërkon që ju të krijoni skedarët tuaj në formatin Markdown. Pastaj, duke përdorur një skedar të vetëm konfigurimi YAML, mund të krijoni një faqe interneti statike që punon për ju.

Tjetra do të shohim se sa e lehtë është të sigurosh një faqe të plotë të dokumentacionit duke përdorur MkDocs. Ka shumë të tjerë gjeneratorët e faqeve statike e ngjashme, por kjo ka një konfigurim dhe implementim nga më të thjeshtat.

Një përdorues normal mund ta përdorë gjithashtu këtë softuer për të krijoni një platformë lokale për të mbajtur shënime për veten e tij ose ndonjë gjë tjetër të ngjashme.

Instaloni MkDocs

Instalo lokalisht

Le të shohim që instalimi i MkDocs është mjaft i lehtë. Ne do të mundemi instaloni atë duke përdorur pip. Thjesht duhet të hapni një terminal (Ctrl + Alt + T) dhe të shkruani në të:

pip install mkdocs

Pas instalimit, në drejtorinë tuaj të punës, ekzekutoni komandën e mëposhtme për të inicializoni një sit:

mkdocs new mkdocspro

Dhe pastaj për të filloni ta shërbeni atë drejtuar:

cd mkdocspro

mkdocs serve

Atëherë mundeni shkoni në localhost: 8000 (ose adresën tuaj IP / emrin e hostit me portin 8000) për të parë se si funksionon MkDocs.

Instaloni në serverin tuaj nginx

Meqenëse ky është një gjenerator i faqeve statike, nuk ka nevojë për motor backend si PHP ose Python. Ju do të jeni në gjendje të implementoni projektin MkDocs në serverin tuaj të internetit (nginx, apache2) në një minutë. Për shembull, këtu është konfigurimi i hostit virtual nginx:

server {
        server_name ejemplo.com;

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

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

Zëvendëson shembull.com me domenin që keni në serverin tuaj. Ju gjithashtu do të duhet të ndryshoni / var / www / mkdocspro / site nga rruga e nënfolderit të faqes në serverin tuaj. Atëherë kemi vetëm rinisni nginx me komandën e mëposhtme:

sudo service nginx restart

Tani mund të drejtoheni tek example.com dhe ta shihni se funksionon.

Instaloni një temë tjetër në Mkdocs

Tema e paracaktuar e Mkdocs nuk është veçanërisht e mirë. Por mund të instaloni një tjetër në një minutë. Një shembull i instalimit të një teme tjetër, do të jetë më poshtë. Me të cilën do të shkojmë instaloni temën e materialit:

pip install mkdocs-material

Pas instalimit, për të aktivizuar temën, do t'ju duhet redaktoni skedarin tuaj mkdocs.yml dhe bëjeni të ngjashëm me këtë. Disa mundësi mund të shtohen:

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'

Opsionet janë mjaft të qarta. Por këtu janë disa shpjegime:

• repo_url: eshte URL e depozitës së Git. Nëse planifikoni të integroni Git direkt në projektin tuaj MkDocs, mund ta përdorni këtë mundësi për të lejuar që njerëzit të modifikojnë faqet ose pirunin e projektit.
• redakto_uri: Kjo është postfix për redaktimin e faqeve në GitHub. Mund ta ndryshoni nëse jeni duke përdorur GitLab ose GitBucket.
• google_analytics: Nuk ka asnjë panel kontrolli për MkDocs. Prandaj, për të ditur që viziton faqen tënde të internetit, duhet të përdorësh Google Analytics. Ky opsion do t'ju lejojë të futni numrin tuaj të ndjekjes për të lidhur llogarinë tuaj me faqen e internetit.
• Disqus: Nëse dëshironi mundësoni sistemin e komentimit Disqus në faqen e internetit, mund të vendosni emrin tuaj të shkurtër këtu.
• temë: Të emrin e temës që dëshironi të përdorni. Do të duhet ta instaloni më parë, siç bëmë vetëm me temën e materialit. Ky do të jetë emri që do të përdorim në shembull.

Shihni ndryshimet e temës së re

Pas ruajtjes së skedarit, ekzekutoni ndërtimin e mkdocs brenda dosjes mkdocsproject. Uebfaqja juaj do të miratojë pamjen dhe ndjesinë e paracaktuar të temës Materiali:

Rëndësishme: sigurohuni që gjithmonë të ekzekutoni ndërtimin e mkdocs pas çdo modifikimi që ju bëni në skedarë. Përndryshe nuk do të shihni ndonjë ndryshim.

Ka shumë temat dhe opsionet e tjera për të konfiguruar këtë softuer. Ju mund t'i këshilloni ata në dokumentacioni zyrtar nga MkDocs. Këtu është një listë e opsionet e mundshme që mund të përdorim.