Mkdocs, izveidojiet dokumentāciju, pateicoties šai atvērtā pirmkoda programmatūrai

Nākamajā rakstā mēs ieskatīsimies Mkdocs. Ja izstrādājat programmatūru un meklējat platforma dokumentācijas izveidošanai vienam no jūsu projektiem. Vai arī, ja jūs strādājat uzņēmumā, kuram personālam jāizveido iekšēja dokumentācija. Pat ja esat pieredzējis lietotājs, kurš vēlas saglabāt dažas piezīmes. MkDocs ir rīks, kuru jums vajadzētu izmēģināt.

Šī programmatūra ir statisks vietņu ģenerators, kura mērķis ir izveidot dokumentācijas platformas. Tas ir diezgan vienkārši, diezgan izskatīties un viegli uzstādāms un izvietojams. Ir rakstīts pitonā un vienkārši prasa, lai jūs izveidotu failus Markdown formātā. Pēc tam, izmantojot vienu YAML konfigurācijas failu, varat ģenerēt statisku vietni, kas jums der.

Tālāk mēs redzēsim, cik viegli ir iegūt pilnīgu dokumentācijas vietni, izmantojot MkDocs. Ir daudz citu vietņu ģeneratori līdzīgs statisks, bet tas ir vienkāršākā konfigurācija un ieviešana.

Normāls lietotājs varētu arī izmantot šo programmatūru izveidojiet vietējo platformu piezīmju veikšanai sev vai kam citam līdzīgam.

Instalējiet MkDocs

Instalējiet lokāli

Apskatīsim, ka MkDocs instalēšana ir diezgan vienkārša. Mēs varēsim instalējiet to, izmantojot pip. Jums vienkārši jāatver terminālis (Ctrl + Alt + T) un tajā jāieraksta:

pip install mkdocs

Pēc instalēšanas savā darba direktorijā izpildiet šādu komandu inicializēt vietni:

mkdocs new mkdocspro

Un tad uz sāciet to pasniegt palaist:

cd mkdocspro

mkdocs serve

Tad jūs varat dodieties uz vietējo hostu: 8000 (vai jūsu IP adrese / resursdatora nosaukums ar portu 8000), lai redzētu, kā darbojas MkDocs.

Instalējiet savā nginx serverī

Tā kā tas ir statisks vietnes ģenerators, nav vajadzīgs neviens aizmugures motors, piemēram, PHP vai Python. MkDocs projektu savā tīmekļa serverī (nginx, apache2) varēsiet īstenot minūtes laikā. Piemēram, šeit ir nginx virtuālā resursdatora konfigurācija:

server {
        server_name ejemplo.com;

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

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

Aizstāj example.com ar domēnu, kas atrodas jūsu serverī. Jums arī būs jāmainās / var / www / mkdocspro / site servera vietnes apakšmapes ceļu. Tad mums ir tikai restartējiet nginx ar šādu komandu:

sudo service nginx restart

Tagad varat doties uz vietni example.com un redzēt, kā tā darbojas.

Mkdocs instalējiet citu motīvu

Noklusējuma Mkdocs tēma nav īpaši laba. Bet vēl vienu jūs varat instalēt minūtes laikā. Citas tēmas instalēšanas piemērs būs šāds. Ar ko mēs ejam instalēt materiāla tēmu:

pip install mkdocs-material

Pēc instalēšanas, lai aktivizētu motīvu, jums tas būs jādara rediģējiet failu mkdocs.yml un padariet to līdzīgu šim. Var pievienot dažas opcijas:

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'

Iespējas ir diezgan skaidras. Bet šeit ir daži paskaidrojumi:

• repo_url: ir Git repozitorija URL. Ja plānojat integrēt Git tieši savā MkDocs projektā, varat izmantot šo opciju, lai ļautu cilvēkiem rediģēt lapas vai dakšu projektu.
• rediģēt_uri: Tas ir postfix lapu rediģēšanai vietnē GitHub. To var mainīt, ja izmantojat GitLab vai GitBucket.
• google_analytics: MkDocs nav vadības paneļa. Tāpēc, lai zinātu kas apmeklē jūsu vietni, jums jāizmanto Google Analytics. Šī opcija ļaus jums ievietot izsekošanas numuru, lai jūsu kontu saistītu ar vietni.
• Disqus: Ja tu vēlies iespējot Disqus komentēšanas sistēmu vietnē varat ievietot savu īso vārdu šeit.
• tēma: The tēmas nosaukums, kuru vēlaties izmantot. Jums tas būs jāinstalē iepriekš, kā mēs tikko to izdarījām ar materiāla tēmu. Tas būs nosaukums, kuru mēs izmantosim piemērā.

Skatiet jaunās tēmas izmaiņas

Pēc faila saglabāšanas palaidiet mkdocs build mapē mkdocsproject. Jūsu vietne pieņems Materiālu motīva noklusējuma izskatu:

Svarīgi: pēc katras modifikācijas vienmēr palaidiet mkdocs build ko darāt failos. Pretējā gadījumā jūs neredzēsiet nekādas izmaiņas.

ir daudz citas tēmas un iespējas lai konfigurētu šo programmatūru. Jūs varat konsultēties ar viņiem vietnē oficiālā dokumentācija autors MkDocs. Šeit ir saraksts ar iespējamās iespējas ko mēs varam izmantot.