Мкдоцс, креирајте документацију захваљујући овом софтверу отвореног кода

У следећем чланку ћемо погледати Мкдоцс. Ако развијате софтвер и тражите платформа за креирање документације за један од ваших пројеката. Или ако радите у компанији која треба да креира интерну документацију за особље. Чак и ако сте напредни корисник који жели да сачува неке белешке. МкДоцс је алат који бисте требали испробати.

Овај софтвер је статички генератор веб страница чији је циљ стварање платформи за документацију. Прилично је једноставно, лепо је погледати и лако се поставља и примењује. Је написан питоном и једноставно захтева да креирате датотеке у формату Маркдовн. Затим, користећи једну ИАМЛ датотеку за конфигурацију, можете да генеришете статичну веб локацију која вам одговара.

Даље ћемо видети како је лако добити комплетну веб страницу са документацијом користећи МкДоцс. Много је других генератори сајтова слична статичка, али ово има конфигурацију и имплементацију најједноставнијег.

Нормалан корисник такође може да користи овај софтвер за створити локалну платформу за вођење белешки за себе или било шта друго слично.

Инсталирајте МкДоцс

Инсталирајте локално

Да видимо да је инсталирање МкДоцс прилично једноставно. Моћи ћемо инсталирајте га помоћу пип-а. Само треба да отворите терминал (Цтрл + Алт + Т) и у њега напишете:

pip install mkdocs

Након инсталације, у свом радном директоријуму покрените следећу наредбу за иницијализујте локацију:

mkdocs new mkdocspro

А онда да почните да га служите трцати:

cd mkdocspro

mkdocs serve

Онда можете идите на лоцалхост: 8000 (или вашу ИП адресу / име хоста са портом 8000) да бисте видели како МкДоцс ради.

Инсталирајте на нгинк сервер

Пошто је ово статички генератор сајта, није потребан позадински механизам попут ПХП-а или Питхона. За минут ћете моћи да примените пројекат МкДоцс на свом веб серверу (нгинк, апацхе2). На пример, овде је нгинк конфигурација виртуелног хоста:

server {
        server_name ejemplo.com;

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

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

Замењује ејемпло.цом са доменом који имате на серверу. Такође ћете морати да се промените / вар / ввв / мкдоцспро / сите путањом до подмапе локације на вашем серверу. Онда имамо само поново покрените нгинк са следећом командом:

sudo service nginx restart

Сада можете да одете на екампле.цом и видите како то функционише.

Инсталирајте другу тему у Мкдоцс

Подразумевана тема Мкдоцс није нарочито добра. Али за минут можете да инсталирате још један. Пример инсталације друге теме биће следећи. Са којим ћемо инсталирати тему материјала:

pip install mkdocs-material

Након инсталације, да бисте активирали тему, мораћете уредите своју датотеку мкдоцс.имл и учините је сличном овој. Неке опције се могу додати:

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'

Опције су сасвим јасне. Али ево неколико објашњења:

• репо_урл: је УРЛ Гит спремишта. Ако планирате да интегришете Гит директно у свој МкДоцс пројекат, можете да користите ову опцију да омогућите људима да уређују странице или рачвају пројекат.
• едит_ури: Ово је постфик за уређивање страница на ГитХуб-у. Можете га променити ако користите ГитЛаб или ГитБуцкет.
• гоогле_аналитицс: Не постоји контролна табла за МкДоцс. Према томе, знати ко посети вашу веб страницу, морате користити Гоогле аналитику. Ова опција ће вам омогућити да уметнете свој број за праћење да бисте свој рачун повезали са веб локацијом.
• дискус: Ако желиш омогућити Дискус систем коментарисања на веб локацији можете овде убацити своје кратко име.
• тема: Тхе назив теме коју желите да користите. Мораћете да га инсталирате раније, као што смо управо урадили са темом материјала. Ово ће бити име које ћемо користити у примеру.

Погледајте промене у новој теми

Након чувања датотеке, покрените мкдоцс буилд унутар фасцикле мкдоцспројецт. Ваша веб локација ће усвојити задати изглед и стил теме Материјал:

Важно: побрините се да увек изводите мкдоцс буилд после сваке модификације што радите у датотекама. У супротном нећете видети никакве промене.

Има их много друге теме и опције за конфигурисање овог софтвера. Можете их консултовати у званична документација би МкДоцс. Ево листе могуће опције које можемо користити.