Mkdocs, buat dokumentasi berkat perisian sumber terbuka ini

Dalam artikel seterusnya kita akan melihat Mkdocs. Sekiranya anda mengembangkan perisian dan mencari platform untuk membuat dokumentasi untuk salah satu projek anda. Atau jika anda bekerja di syarikat yang perlu membuat dokumentasi dalaman untuk kakitangan. Walaupun anda pengguna lanjutan yang ingin menyimpan beberapa nota. MkDocs adalah alat yang mesti anda cuba.

Perisian ini adalah penjana laman web statik yang bertujuan untuk membuat platform dokumentasi. Cukup sederhana, cantik untuk dilihat, dan senang disusun dan digunakan. Adakah ditulis dalam python dan secara sederhana menghendaki anda membuat fail anda dalam format Markdown. Kemudian, dengan menggunakan satu fail konfigurasi YAML, anda boleh menghasilkan laman web statik yang sesuai untuk anda.

Selanjutnya kita akan melihat betapa mudahnya mendapatkan laman web dokumentasi lengkap menggunakan MkDocs. Terdapat banyak yang lain penjana laman web statik serupa, tetapi ini mempunyai konfigurasi dan pelaksanaan yang paling mudah.

Pengguna biasa juga boleh menggunakan perisian ini untuk buat platform tempatan untuk mencatat untuk dirinya sendiri atau perkara lain yang serupa.

Pasang MkDocs

Pasang secara tempatan

Mari kita lihat bahawa memasang MkDocs agak mudah. Kami akan dapat memasangnya menggunakan pip. Anda hanya perlu membuka terminal (Ctrl + Alt + T) dan tulis di dalamnya:

pip install mkdocs

Selepas pemasangan, di direktori kerja anda, jalankan arahan berikut ke memulakan laman web:

mkdocs new mkdocspro

Dan kemudian ke mula menghidangkannya jalankan:

cd mkdocspro

mkdocs serve

Maka anda boleh pergi ke localhost: 8000 (atau alamat IP / nama host anda dengan port 8000) untuk melihat bagaimana MkDocs berfungsi.

Pasang pada pelayan nginx anda

Oleh kerana ini adalah penjana laman web statik, tidak diperlukan mesin backend seperti PHP atau Python. Anda akan dapat melaksanakan projek MkDocs di pelayan web anda (nginx, apache2) dalam satu minit. Sebagai contoh, berikut adalah konfigurasi hos maya nginx:

server {
        server_name ejemplo.com;

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

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

Mengganti example.com dengan domain yang anda ada di pelayan anda. Anda juga harus berubah / var / www / mkdocspro / laman web mengikut jalan subfolder laman web di pelayan anda. Kemudian kita hanya mempunyai mulakan semula nginx dengan arahan berikut:

sudo service nginx restart

Sekarang anda boleh pergi ke example.com dan melihatnya berfungsi.

Pasang tema lain di Mkdocs

Tema Mkdocs lalai tidak begitu baik. Tetapi anda boleh memasang yang lain dalam satu minit. Contoh pemasangan tema lain, adalah seperti berikut. Dengan mana kita akan pergi memasang tema bahan:

pip install mkdocs-material

Selepas pemasangan, untuk mengaktifkan tema, anda perlu edit fail mkdocs.yml anda dan buat yang serupa dengan ini. Beberapa pilihan boleh ditambah:

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'

Pilihannya cukup jelas. Tetapi berikut adalah beberapa penjelasan:

• repo_url: adalah URL git repositori. Sekiranya anda merancang untuk menggabungkan Git secara langsung ke dalam projek MkDocs anda, anda boleh menggunakan pilihan ini untuk membolehkan orang mengedit halaman atau membelenggu projek tersebut.
• sunting_uri: Ini adalah postfix untuk mengedit halaman di GitHub. Anda boleh mengubahnya jika menggunakan GitLab atau GitBucket.
• google_analytics: Tidak ada panel kawalan untuk MkDocs. Oleh itu, untuk mengetahui yang melayari laman web anda, anda mesti menggunakan Google Analytics. Pilihan ini akan membolehkan anda memasukkan nombor penjejakan untuk mengaitkan akaun anda dengan laman web.
• Disqus: Sekiranya anda mahu aktifkan sistem komen Disqus di laman web, anda boleh memasukkan nama pendek anda di sini.
• tema: The nama tema yang ingin anda gunakan. Anda mesti memasangnya sebelumnya, seperti yang baru kita lakukan dengan tema material. Ini akan menjadi nama yang akan kita gunakan dalam contoh.

Lihat perubahan tema baru

Setelah menyimpan fail, jalankan mkdocs build di dalam folder mkdocsproject. Laman web anda akan menggunakan rupa dan nuansa tema Material:

Penting: pastikan sentiasa menjalankan mkdocs build selepas setiap pengubahsuaian yang anda lakukan dalam fail. Jika tidak, anda tidak akan melihat perubahan.

Terdapat banyak tema dan pilihan lain untuk mengkonfigurasi perisian ini. Anda boleh berjumpa dengan mereka di dokumentasi rasmi oleh MkDocs. Berikut adalah senarai pilihan yang mungkin yang boleh kita gunakan.