Membina dokumentasi produk dengan mkdocs

Terdapat pepatah yang popular bahawa "produk adalah sebaik dokumentasinya". Ini berlaku untuk perisian seperti yang dilakukan untuk produk fizikal.

Sebagai pemaju kecil, indie yang tidak pakar dalam reka bentuk front-end, saya sering menyewa seorang freelancer untuk membina laman web produk saya-yang, tentu saja, biasanya termasuk bahagian dokumentasi.

Bahagian dokumentasi boleh mengambil sedikit masa dan wang untuk membina, walaupun untuk produk yang mudah, jadi ia akan menjadi baik untuk tidak mencipta semula roda untuk setiap tapak. Nasib baik, ada cara.

Takeaways Key

Mkdocs adalah penjana tapak statik yang ideal untuk membina dokumentasi projek; Ia ringan, mudah untuk menjadi tuan rumah, dan boleh digunakan untuk tapak yang berdiri sendiri atau bahagian dokumentasi tapak yang lebih besar.
untuk menggunakan Mkdocs, Python dan Pip (Pengurus Pakej Python) mesti dipasang pada komputer anda; MKDOCS dipasang secara tempatan di komputer anda, membolehkan anda membina dokumentasi anda di luar talian.
Mkdocs membolehkan penyesuaian dengan pelbagai tema dan keupayaan untuk menambah halaman baru melalui fail konfigurasi Mkdocs.yml; Ia juga termasuk pelayan web terbina dalam untuk pratonton tempatan dokumentasi.
Dokumentasi yang dibina dengan mkdocs boleh dihoskan secara percuma pada perkhidmatan seperti halaman GitHub dan membaca dokumen, atau pada pelayan anda sendiri; MKDOCS juga menyokong penempatan ke platform ini secara langsung.

Memperkenalkan Mkdocs

MKDOCS adalah penjana tapak statik percuma yang ditujukan untuk membina dokumentasi projek. Ia boleh digunakan untuk menjana tapak yang berdiri sendiri, atau hanya seksyen dokumentasi tapak yang lebih besar.

Kerana MKDOCs menghasilkan fail statik, dokumentasi anda adalah ringan dan mudah untuk menjadi tuan rumah menggunakan perkhidmatan percuma seperti halaman GitHub dan membaca dokumen-atau tentu saja pada pelayan anda sendiri.

Dalam artikel ini, saya akan memperkenalkan MKDOCS, menunjukkan kepada anda cara memasangnya, membina dokumentasi dengannya dan akhirnya menjadi tuan rumah dokumentasi yang dihasilkan pada pelayan web.

Untuk mendapatkan rasa jenis dokumentasi Mkdocs menghasilkan, lihat dokumentasi Plugin Profile WordPress saya, yang dibina dengan mkdocs menggunakan tema baca Dokumen.

Mkdocs ditulis dalam Python. Fail sumber dokumentasi ditulis dalam markdown, dan dikonfigurasikan dengan fail konfigurasi YAML tunggal.

Untuk membina dokumentasi dengan mkdocs, anda perlu memasangnya secara tempatan di komputer anda. Oleh itu mari kita lihat bagaimana untuk memasangnya.

memasang python dan mkdocs

Penjana tapak statik seperti Jekyll (digunakan terutamanya untuk blog, dan dibina di atas Ruby) dan Mkdocs memerlukan beberapa corong baris arahan, jadi diberi amaran. Walau bagaimanapun, kepada mereka yang tidak digunakan untuk bekerja dengan baris arahan, saya menggalakkan anda membaca dan mencubanya, kerana ia tidak begitu buruk kerana ia kelihatan!

memasang python dan pip

Untuk memasang mkdocs, anda perlu mempunyai python dan pip (pengurus pakej python) yang dipasang di komputer anda. Mereka mungkin sudah dipasang di komputer anda. Jika anda mempunyai Python 3.4 atau lebih baru dipasang, anda mungkin memasang PIP. (Lihat panduan pemasangan Python untuk arahan penuh.)

Untuk memasang python pada taburan Linux seperti Ubuntu, lihat benang StackOverflow ini atau melakukan carian Google untuk pengedaran anda.

untuk Windows, muat turun pemasang versi pilihan anda dan jalankan fail untuk memasang python.

Sebagai alternatif, jika anda mempunyai pengurus pakej coklat yang dipasang di mesin anda, jalankan Choco Pasang Python.

Untuk mengesahkan bahawa pengedaran python anda telah dipasang PIP, jalankan perintah PIP -version. Jika tidak, jalankan python get-pip.py atau choco memasang pip melalui coklat untuk mendapatkannya dipasang.

Memasang mkdocs

Sekarang bahawa Python dan Pip dipasang, jalankan Pip Pasang mkdocs untuk memasang mkdocs.

Untuk mengesahkan segala -galanya baik -baik saja, jalankan Mkdocs membantu untuk memberikan perintah mkdocs cuba.

Jika anda berada di Windows dan perintah MKDOCS tidak hidup, pastikan untuk menambah C: Path-to-Python-Folderscripts ke PATH Variable Alam Sekitar.

Membina dokumentasi

Sekarang anda mempunyai Python dan Mkdocs yang disediakan, anda boleh meneruskan dengan dokumentasi sebenar anda.

Pertama, buat projek untuk dokumentasi (mari kita panggil SP-DOC) dan menavigasi ke folder yang dibuat:

$ mkdocs new sp-doc
$ cd sp-doc

Folder projek yang dihasilkan akan mengandungi folder DOCS -di mana fail markdown untuk dokumentasi akan disimpan -dan fail konfigurasi mkdocs.yml.

inilah struktur direktori:

|-- docs              # MD doc pages
    |-- index.md
|-- mkdocs.yml        # config file

Tambahkan konfigurasi minimum terdedah berikut ke fail mkdocs.yml:

site_name: SitePoint Documentation
site_description: Description of the documentation
theme: readthedocs
pages:
- ['index.md', 'Index']

Mkdocs kapal dengan beberapa tema -seperti "Mkdocs", "Baca Dokumen" dan "Bootstrap". Katakan anda berhasrat menggunakan tema lalai. Dalam kes itu, hanya gantikan readthedocs dengan mkdocs dalam kod di atas.

Konfigurasi halaman digunakan untuk menentukan set halaman yang harus dibina untuk dokumentasi dan menu navigasi.

fail markdown yang ditambahkan ke halaman mestilah relatif kepada folder DOCS. Sebagai contoh, jika anda membuat folder baru yang dipanggil Config di dalam direktori Docs dan menambah fail persediaan.md di dalamnya, inilah cara anda akan menambahkannya ke halaman dalam konfigurasi fail mkdocs.yml:

site_name: SitePoint Documentation
site_description: Description of the description
theme: readthedocs
pages:
- ['index.md', 'Index']
- ['start.md', 'Get Started']
- ['config/setup.md', 'Configuration', 'Setup']
- ['config/debug.md', 'Configuration', 'Debug']

Ini mewujudkan beberapa halaman baru yang muncul secara automatik dalam menu dokumentasi kami. Pertama, ada halaman Start.md, dengan tajuk "Bermula".

Kami juga telah menambah seksyen baru ke menu dokumentasi yang dipanggil "Konfigurasi", di mana terdapat pautan ke halaman persediaan dan debug baru.

mkdocs termasuk pelayan web terbina dalam, jadi anda boleh pratonton dokumentasi anda secara tempatan semasa anda bekerja di atasnya.

3

Lawati http://127.0.0.1:8000 dalam penyemak imbas anda untuk melihat dokumentasi:

Jika anda berpuas hati dengan apa yang telah anda buat, jalankan mkdocs membina untuk menghasilkan fail statik untuk dokumentasi yang akan disimpan ke direktori tapak.

anda boleh menyalin fail statik dan menjadi tuan rumah pada pelayan web pilihan anda untuk mengambil dokumentasi secara langsung.

Di bahagian seterusnya, kami akan belajar bagaimana untuk menggunakan MKDOCS untuk membaca halaman Dokumen dan GitHub.

Menggunakan Mkdocs

Pertama, buat repositori github (atau bitbucket) untuk menyimpan fail.

Jalankan arahan berikut untuk digunakan ke GitHub di mana https://github.com/collizo4sky/sitepoint_mkdocs adalah mkdocs saya sendiri:

$ mkdocs new sp-doc
$ cd sp-doc

Mari kita gunakan fail dokumentasi kami untuk membaca dokumen, perkhidmatan dokumentasi percuma.

Baca dokumen

Pertama, buat akaun jika anda tidak mempunyai satu dan log masuk.

Klik butang Import atau klik item menu Tambah Projek.

Anda boleh memilih untuk menyambungkan akaun GitHub atau Bitbucket anda untuk membaca dokumen untuk mengimport keseluruhan projek anda. Sebaliknya, kami akan pergi dengan pengimportan manual, dengan mengklik butang projek import secara manual.

isi borang seperti yang ditunjukkan dalam imej di bawah:

Berjaya mengimport dokumen dari GitHub, anda akan diarahkan ke halaman projek:

Anda boleh melihat dokumentasi kami yang dihasilkan di http://sitePoint-doc.readthedocs.org/en/latest/.

Jika anda mahukan dokumentasi di subdomain, tunjuk rekod CNAME dalam DNS anda ke subdomain untuk projek anda.

Contohnya, untuk membuat dokumentasi tersedia di docs.sitePoint.com, buat rekod CNAME yang menunjuk ke sitePoint-doc.readthedocs.org.

GitHub Pages

Sekarang mari kita lihat bagaimana untuk menjadi tuan rumah dokumentasi kami di halaman GitHub, satu lagi perkhidmatan hosting percuma.

Pastikan anda berada di cawangan kerja repositori git -yang merupakan cawangan induk dalam kes kami.

Jalankan perintah mkdocs gh-deploy ---bean

Di sebalik tabir, arahan ini akan membina dokumen anda dan melakukan mereka ke cawangan GH-PAGES dan kemudian menolak cawangan ke GitHub.

Berikut adalah demo dokumen Sitepoint kami di halaman GitHub.

Pembekal lain

Mana -mana penyedia hosting yang boleh menyampaikan fail statik boleh digunakan untuk menyampaikan dokumentasi yang dihasilkan oleh MKDOCS. Garis panduan berikut harus memberikan bantuan umum.

Apabila anda membina laman web anda menggunakan arahan MKDOCS Build, semua fail ditulis ke direktori yang diberikan kepada pilihan konfigurasi SITE_DIR (lalai ke "tapak") dalam fail config mkdocs.yaml anda.

Cukup salin kandungan direktori itu ke direktori root pelayan penyedia hosting anda dan anda sudah selesai. Atau, jika dokumen anda hanya akan menjadi subseksyen laman web anda, gerakkan fail ke subfolder yang ditetapkan.

Ringkasan

Dalam tutorial ini, kami belajar bagaimana membina dokumentasi dengan MKDOCS, penjana laman web python statik, dan juga cara menggunakan dan menjadi tuan rumah dokumentasi secara percuma di halaman GitHub dan membaca dokumen.

Adakah anda pernah menggunakan mkdocs sebelum ini? Jika tidak, adakah anda mempertimbangkan menggunakannya? Bagaimana anda sedang berurusan dengan dokumentasi berkhidmat kepada pengguna anda? Saya suka mendengar maklum balas anda atau menjawab sebarang soalan yang mungkin anda miliki.

Soalan Lazim (Soalan Lazim) Mengenai Bangunan Produk Dokumentasi dengan Mkdocs

Apakah prasyarat untuk menggunakan mkdocs?

Untuk menggunakan mkdocs, anda perlu memasang python pada sistem anda. MKDOCS menyokong versi Python 2.7, 3.5, 3.6, 3.7, 3.8, dan PYPY. Anda boleh menyemak versi python anda dengan menaip python -versi dalam arahan arahan anda. Jika Python berjaya dipasang, nombor versi akan dipaparkan. Jika tidak, anda perlu memasang Python terlebih dahulu. Selepas Python dipasang, anda boleh memasang mkdocs menggunakan PIP, pemasang pakej Python. Taipkan Pip Pasang Mkdocs dalam arahan arahan anda untuk memasang mkdocs.

Bagaimana saya boleh menyesuaikan rupa tapak Mkdocs saya? Tema lalai dipanggil "Mkdocs", tetapi terdapat banyak tema lain yang tersedia. Anda boleh menukar tema dengan mengedit fail konfigurasi mkdocs.yml. Di bawah bahagian tema, ganti MKDOCS dengan nama tema yang anda inginkan. Beberapa tema juga membenarkan penyesuaian selanjutnya dengan menambah fail CSS atau JavaScript tersuai. fail dalam direktori dokumen anda. Nama fail akan digunakan sebagai URL untuk halaman. Kemudian, tambahkan entri baru ke bahagian halaman fail konfigurasi mkdocs.yml anda. Formatnya ialah - ['Tajuk Halaman', 'FileName.md']. Tajuk halaman akan digunakan sebagai teks pautan dalam menu navigasi.

Bagaimana saya menggunakan laman MKDOCS saya? Cukup jalankan Mkdocs GH-Deploy dari command prompt anda, dan Mkdocs akan membina laman web anda dan menolaknya ke cawangan GH-halaman repositori GitHub anda. Sekiranya anda ingin menggunakan pembekal yang berbeza, anda perlu membina tapak dengan MKDOCS membina dan kemudian memuat naik fail tapak secara manual.

Bolehkah saya menggunakan mkdocs dengan membaca dokumen? Untuk menggunakan mkdocs dengan membaca dokumen, anda perlu membuat fail konfigurasi. Readthedocs.yml dalam akar repositori anda dan tentukan Mkdocs sebagai jenis dokumentasi. > Anda boleh mengemas kini mkdocs dengan menjalankan pemasangan PIP -upgrade mkdocs dalam command prompt anda. Ini akan memuat turun dan memasang versi terkini MKDOCS.

Bolehkah saya menggunakan MKDOCS untuk dokumentasi peribadi? Walau bagaimanapun, jika anda menggunakan penggunaan halaman GitHub terbina dalam, dokumentasi anda boleh diakses secara terbuka. Sekiranya anda perlu menyimpan dokumentasi anda secara peribadi, anda boleh menggunakan penyedia hosting yang berbeza yang menyokong perlindungan kata laluan atau kawalan akses.

Bagaimana saya menambah fungsi carian ke laman MKDOCS saya? Tema termasuk fungsi carian terbina dalam. Jika tema anda tidak termasuk carian, atau jika anda ingin menggunakan penyedia carian yang berbeza, anda boleh menambah plugin carian ke fail konfigurasi mkdocs.yml anda. Dokumentasi?

Mkdocs direka untuk menghasilkan laman web HTML, bukan PDF. Walau bagaimanapun, terdapat alat dan perkhidmatan pihak ketiga yang boleh menukar laman MKDOCS anda ke PDF. Dari bahagian halaman fail konfigurasi mkdocs.yml anda. Setiap entri di bahagian halaman menjadi pautan dalam menu navigasi. Perintah pautan sepadan dengan urutan penyertaan di bahagian halaman.

Atas ialah kandungan terperinci Membina dokumentasi produk dengan mkdocs. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!