Mkdocs, luo dokumentaatiota tämän avoimen lähdekoodin ohjelmiston ansiosta

Seuraavassa artikkelissa aiomme tarkastella Mkdocsia. Jos kehität ohjelmistoja ja etsit alustan dokumentaation luomiseen yhdelle projektistasi. Tai jos työskentelet yrityksessä, jonka on luotava henkilöstölle sisäinen dokumentaatio. Vaikka olisit edistynyt käyttäjä, joka haluaa tallentaa muistiinpanoja. MkDocs on työkalu, jota kannattaa kokeilla.

Tämä ohjelmisto on staattinen sivustogeneraattori, jonka tarkoituksena on luoda dokumentointialustoja. Se on melko yksinkertainen, kaunis katsoa ja helppo asentaa ja ottaa käyttöön. On kirjoitettu pythonilla ja yksinkertaisesti vaatii sinua luomaan tiedostosi Markdown-muodossa. Tämän jälkeen voit luoda yhden YAML-määritystiedoston avulla staattisen verkkosivuston, joka toimii sinulle.

Seuraavaksi näemme, kuinka helppoa on saada kattava dokumentointisivusto MkDocsin avulla. On monia muita sivuston generaattorit samanlainen staattinen, mutta tämä on yksinkertaisin kokoonpano ja toteutus.

Normaali käyttäjä voi myös käyttää tätä ohjelmistoa luo paikallinen foorumi muistiinpanojen tekemiseen itselleen tai muulle vastaavalle.

Asenna MkDocs

Asenna paikallisesti

Katsotaanpa, että MkDocsin asentaminen on melko helppoa. Voimme asenna se pipin avulla. Sinun tarvitsee vain avata pääte (Ctrl + Alt + T) ja kirjoittaa siihen:

pip install mkdocs

Suorita seuraava komento asennuksen jälkeen työhakemistoon alustaa sivusto:

mkdocs new mkdocspro

Ja sitten alkaa palvella sitä juosta:

cd mkdocspro

mkdocs serve

Sitten voit mene paikalliseen isäntään: 8000 (tai IP-osoitteesi / isäntänimesi portilla 8000) nähdäksesi kuinka MkDocs toimii.

Asenna nginx-palvelimellesi

Koska tämä on staattinen sivustogeneraattori, ei tarvita taustamoottoria, kuten PHP tai Python. Pystyt toteuttamaan MkDocs-projektin verkkopalvelimellasi (nginx, apache2) minuutissa. Esimerkiksi tässä on nginx-virtuaalipalvelimen kokoonpano:

server {
        server_name ejemplo.com;

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

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

Korvaa ejemplo.com palvelimellasi olevan verkkotunnuksen kanssa. Sinun on myös muutettava / var / www / mkdocspro / site palvelimesi sivuston alikansiopolun kautta. Sitten meillä on vain Käynnistä nginx uudelleen seuraavalla komennolla:

sudo service nginx restart

Nyt voit siirtyä osoitteeseen example.com ja nähdä sen toimivan.

Asenna toinen teema Mkdocsiin

Mkdocs-oletusteema ei ole erityisen hyvä. Mutta voit asentaa toisen minuutissa. Seuraava esimerkki toisen teeman asennuksesta on seuraava. Millä olemme menossa asenna materiaaliteema:

pip install mkdocs-material

Asennuksen jälkeen sinun on aktivoitava teema muokkaa mkdocs.yml-tiedostoa ja tee siitä samanlainen kuin tämä. Joitakin vaihtoehtoja voidaan lisätä:

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'

Vaihtoehdot ovat melko selkeät. Mutta tässä on joitain selityksiä:

• repo_url: on Git-arkiston URL-osoite. Jos aiot integroida Gitin suoraan MkDocs-projektiisi, voit käyttää tätä vaihtoehtoa, jotta ihmiset voivat muokata sivuja tai haarauttaa projektia.
• edit_uri: Tämä on postfix sivujen muokkaamiseen GitHubissa. Voit muuttaa sitä, jos käytät GitLabia tai GitBucketia.
• google_analytics: MkDocsille ei ole ohjauspaneelia. Siksi tietää joka vierailee verkkosivustollasi, sinun on käytettävä Google Analyticsia. Tämän vaihtoehdon avulla voit lisätä seurantanumerosi liittääksesi tilisi verkkosivustoon.
• Disqus: Jos haluat ota Disqus-kommentointijärjestelmä käyttöön verkkosivustolla voit lisätä lyhyen nimesi tähän.
• teema: Tällä käytettävän teeman nimi. Sinun on asennettava se aiemmin, kuten teimme juuri materiaaliteeman kanssa. Tätä nimeä käytämme esimerkissä.

Katso uuden teeman muutokset

Tiedoston tallentamisen jälkeen Suorita mkdocs build mkdocsproject-kansion sisällä. Verkkosivustosi hyväksyy Materiaaliteeman oletusarvoisen ulkoasun:

Tärkeää: muista aina suorittaa mkdocs build aina jokaisen muokkauksen jälkeen mitä teet tiedostoissa. Muuten et näe mitään muutosta.

On monia muut teemat ja vaihtoehdot määrittääksesi tämän ohjelmiston. Voit tutustua heihin viralliset asiakirjat kirjoittanut MkDocs. Tässä on luettelo mahdollisia vaihtoehtoja jota voimme käyttää.