Mkdocs, izradite dokumentaciju zahvaljujući ovom softveru otvorenog koda

U sljedećem ćemo članku pogledati Mkdocs. Ako razvijate softver i tražite platforma za izradu dokumentacije za jedan od vaših projekata. Ili ako radite u tvrtki koja treba izraditi internu dokumentaciju za osoblje. Čak i ako ste napredni korisnik koji želi spremiti neke bilješke. MkDocs je alat koji biste trebali isprobati.

Ovaj softver je statički generator web mjesta usmjeren na stvaranje platformi za dokumentaciju. Prilično je jednostavno, lijepo ga je pogledati i jednostavno postaviti i implementirati. Je napisano pitonom i to jednostavno zahtijeva da stvorite datoteke u formatu Markdown. Zatim, pomoću jedne YAML konfiguracijske datoteke, možete generirati statično web mjesto koje odgovara vama.

Dalje ćemo vidjeti kako je lako dobiti web stranicu s kompletnom dokumentacijom pomoću MkDocs. Postoje i mnogi drugi generatori web mjesta slična statička, ali ovo ima konfiguraciju i implementaciju najjednostavnijeg.

Normalan korisnik također bi mogao koristiti ovaj softver za stvoriti lokalnu platformu za vođenje bilješki za sebe ili bilo što drugo slično.

Instalirajte MkDocs

Instalirajte lokalno

Idemo vidjeti da je instalacija MkDocsa vrlo jednostavna. Moći ćemo instalirajte ga pomoću pipa. Jednostavno morate otvoriti terminal (Ctrl + Alt + T) i u njega napisati:

pip install mkdocs

Nakon instalacije, u radnom direktoriju pokrenite sljedeću naredbu za inicijalizira web mjesto:

mkdocs new mkdocspro

A onda da počnite ga posluživati trčanje:

cd mkdocspro

mkdocs serve

Onda možeš idite na localhost: 8000 (ili vaša IP adresa / ime hosta s portom 8000) kako biste vidjeli kako MkDocs radi.

Instalirajte na svoj nginx poslužitelj

Budući da je ovo statički generator web mjesta, nije potreban stražnji mehanizam poput PHP-a ili Pythona. Projekt MkDocs moći ćete implementirati na svoj web poslužitelj (nginx, apache2) za minutu. Na primjer, ovdje je nginx konfiguracija virtualnog hosta:

server {
        server_name ejemplo.com;

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

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

Zamjenjuje primjer.com s domenom koju imate na poslužitelju. Morat ćete se i promijeniti / var / www / mkdocspro / site putem podmape web mjesta na vašem poslužitelju. Tada imamo samo ponovno pokrenite nginx sa sljedećom naredbom:

sudo service nginx restart

Sada možete prijeći na example.com i vidjeti kako to radi.

Instalirajte drugu temu u Mkdocs

Zadana tema Mkdocs nije osobito dobra. Ali za minutu možete instalirati još jedan. Primjer instalacije druge teme bit će sljedeći. S kojim ćemo instalirati temu materijala:

pip install mkdocs-material

Nakon instalacije, za aktiviranje teme morat ćete uredite svoju datoteku mkdocs.yml i učinite je sličnom ovoj. Mogu se dodati neke moguć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'

Opcije su sasvim jasne. Ali evo nekoliko objašnjenja:

• repo_url: je URL spremišta Git. Ako planirate integrirati Git izravno u svoj MkDocs projekt, možete koristiti ovu opciju da omogućite ljudima uređivanje stranica ili račvanje projekta.
• uredi_uri: Ovo je postfix za uređivanje stranica na GitHubu. Možete ga promijeniti ako koristite GitLab ili GitBucket.
• google_analytics: Ne postoji upravljačka ploča za MkDocs. Stoga, znati koji posjeti vaše web mjesto, morate koristiti Google Analytics. Ova će vam opcija omogućiti da umetnete svoj broj za praćenje kako biste svoj račun povezali s web mjestom.
• Disqus: Ako želiš omogućiti sustav komentiranja Disqus na web mjestu ovdje možete umetnuti svoje kratko ime.
• tema: The naziv teme koju želite koristiti. Morat ćete ga prethodno instalirati, kao što smo upravo učinili s temom materijala. To će biti ime koje ćemo upotrijebiti u primjeru.

Pogledajte promjene nove teme

Nakon spremanja datoteke, pokrenite mkdocs build unutar mape mkdocsproject. Vaše će web mjesto usvojiti zadani izgled i izgled teme Materijal:

Važno: pobrinite se da uvijek izvodite mkdocs build nakon svake izmjene što radite u datotekama. Inače nećete vidjeti nikakve promjene.

Ima ih mnogo ostale teme i opcije za konfiguriranje ovog softvera. Možete ih konzultirati u službena dokumentacija od strane MkDocs. Evo popisa moguće opcije koje možemo koristiti.