Docs-as-code in action: Mendokumentasikan pustaka Python.

Dokumentasi ialah sumber penting untuk membantu khalayak sasaran anda memahami cara menggunakan produk anda dengan berkesan. Dokumentasi berkualiti tinggi bukan sahaja menyampaikan masalah teras yang diselesaikan oleh produk anda tetapi juga memperkasakan pengguna untuk mencapai hasil yang diinginkan dengan lancar.

Perkara yang sama berlaku untuk perpustakaan dan pakej sumber terbuka. Dokumentasi yang jelas dan boleh diakses adalah penting untuk membimbing pembangun tentang cara mengintegrasikan alatan ini ke dalam projek mereka dengan jayanya.

Dalam beberapa tahun kebelakangan ini, pendekatan Docs-as-Code (DaC) kepada dokumentasi telah mendapat populariti yang ketara. Kaedah ini menganggap dokumentasi sebagai bahagian asas kitaran hayat pembangunan perisian dengan menggunakan alat dan proses yang sama yang diharap oleh pembangun untuk kod.

Kaedah ini diterima secara meluas kerana ia menggalakkan dokumentasi yang konsisten, dikawal versi dan mudah diselenggara yang berkembang bersama produk.

Apakah itu Docs-as-code?

Dalam istilah mudah, DaC ialah kaedah yang melibatkan pengendalian dan penyelenggaraan dokumentasi seperti yang anda lakukan pada kod anda.

Kitaran hayat pembangunan perisian biasa melibatkan 7 peringkat yang termasuk yang berikut:

1. Perancangan
2. Keperluan dan Analisis Pengumpulan
3. Reka bentuk
4. Pengekodan dan pelaksanaan
5. Ujian kod
6. Penyerahan kod
7. Penyelenggaraan kod

Oleh itu, DaC ialah pendekatan baharu yang memastikan dokumentasi melalui peringkat yang sama. Ini memastikan dokumentasi versi dan terkini dengan perubahan perisian.

Pengedaran tanpa DaC

Pengedaran dengan DaC

Walaupun panduan ini mungkin tidak mendalami aspek teori DaC, anda boleh meneroka panduan Pemula untuk artikel Docs-as-code yang menerangkan konsep di sebalik DaC secara terperinci.

Gambaran Keseluruhan Projek

Panduan ini melibatkan pelaksanaan praktikal DaC dengan Python. Anda akan belajar cara mendokumenkan perpustakaan Python sumber terbuka menggunakan Mintlify.

Mintlify ialah penjana tapak statik dan tapak dokumentasi yang digunakan untuk dokumentasi yang dihadapi orang ramai. Ia mudah diselenggara dan digunakan untuk pelbagai keperluan dokumentasi seperti dokumentasi pembangun, dokumentasi API, dll. Ia juga berfungsi dengan baik dengan metodologi DaC.

Tutorial ini ialah sekuel kepada tutorial sedia ada tentang cara membina dan menggunakan perpustakaan Python. Menggunakan metodologi DaC, anda akan belajar cara mendokumentasikan tutorial rujukan yang dibangunkan perpustakaan Python.

Adalah disyorkan supaya anda melengkapkan tutorial sebelumnya sebelum anda meneruskan. Walau bagaimanapun, anda boleh meneruskan jika anda mempunyai projek sedia ada untuk digunakan untuk tutorial ini.

Keperluan projek

Pengetahuan asas tentang Git dan GitHub, cara membuat repositori Github dan cara untuk menolak kod anda ke GitHub yang kami perlukan. Anda juga memerlukan alatan berikut untuk tutorial ini:

• Akaun Mintlify: Anda memerlukan akaun Mintlify yang aktif untuk membuat dokumentasi (langkah-langkah akan diberikan dalam panduan).
• Node.js: Anda memerlukan Node.js versi 18 dan ke atas untuk memasang Mintlify dan mengedit dokumentasi anda secara setempat.

Sediakan dokumentasi Mintlify

Ikuti langkah di bawah untuk menyediakan dokumentasi menggunakan Mintlify:

1. Buat akaun di Mintlify

2. Sediakan akaun Mintlify anda:
Pautan pengesahan akan dihantar ke mel anda. Pautan ini akan mengubah hala anda ke halaman di bawah:

3. Log masuk dengan Github:
Langkah pertama memerlukan anda melog masuk dengan akaun Github anda.

4. Buat repositori (repo) GitHub untuk dokumentasi anda:
Langkah seterusnya memerlukan anda memasang dan membenarkan aplikasi Mintlify pada akaun Github anda. Ini membolehkan Mintlify membuat repo secara automatik untuk dokumen anda

5. Akses repo dokumentasi anda:
Langkah sebelumnya mencipta repo dokumen baharu untuk dokumentasi anda. Semak repositori GitHub anda untuk mendapatkan repo dokumen baharu

Tambahkan dokumentasi pada projek anda

Langkah seterusnya ialah mengklon repo dokumen ke persekitaran setempat anda dan menambahkannya pada projek sedia ada seperti alat pembangun, pakej sumber terbuka, dll. Jika anda sudah melengkapkan tutorial sebelumnya, projek anda akan menjadi ExchangeLibrary.

Ikuti langkah di bawah untuk menambahkan dokumentasi pada projek anda:

1. Buka terminal dan klon repositori dokumen dengan arahan di bawah:

git clone https://github.com/<your github username>/docs 
</your>

2. Salin folder dokumen yang diklon ke projek anda.

3. Buka projek dalam editor kod.

Struktur fail projek anda kini sepatutnya kelihatan seperti ini:

Pratonton dokumentasi secara tempatan

Mintlify membolehkan anda pratonton dokumentasi anda secara setempat sebelum menerbitkannya. Ikuti langkah di bawah untuk menyediakannya:
1. Buka projek anda di terminal
2. Jalankan arahan di bawah untuk memasang Mintlify secara global:

git clone https://github.com/<your github username>/docs 
</your>

3. Tukar kepada folder dokumen dalam projek anda:

npm i -g mintlify

4. Mulakan pelayan mintlify dengan arahan di bawah:

cd docs

Anda sepatutnya melihat mesej seperti di bawah dalam terminal anda:

Buka URL untuk pratonton dokumentasi secara setempat. Kandungan dokumentasi anda ialah templat dokumen permulaan Mintlify. Ini akan berubah apabila anda mula mengedit dokumentasi anda.

Menulis dokumentasi

Dokumentasi Mintlify dikuasakan oleh fail mint.json. Fail ini mengandungi tetapan skema warna, penomboran dan navigasi untuk dokumentasi. Anda boleh menemuinya dalam folder dokumen projek.

Selain itu, fail dokumentasi dalam Mintlify ditulis dalam .mdx. Ia hampir serupa dengan markdown(.md) kecuali ia membenarkan tag dan simbol khas.

Dalam bahagian ini, anda akan belajar cara mengedit tetapan dokumentasi anda dalam fail mint.json dan cara menambah teks serta komponen khas pada dokumentasi anda.

Edit tetapan dokumentasi

Fail mint.json ialah objek JSON yang terdiri daripada skema warna, penomboran, tetapan navigasi, dll. untuk dokumentasi anda. Di bawah ialah senarai tetapan yang tersedia dan maksudnya:

1. Skema warna dan rupa:
Bahagian ini digunakan untuk mencantikkan dan meningkatkan penampilan dokumentasi anda. Ia digunakan untuk menukar logo (untuk kedua-dua mod terang dan gelap), favicon, tajuk dan skema warna untuk dokumentasi. Ia bermula daripada kekunci $schema kepada kekunci warna seperti yang dilihat di bawah:

mintlify dev

2. Pautan navigasi dan butang CTA:
Bahagian ini digunakan untuk menyediakan pautan navigasi dan butang di bahagian atas halaman dokumentasi. Di bawah ialah contoh pautan dan butang navigasi:

Kod di bawah menyediakan pautan navigasi dan butang CTA untuk dokumentasi Mintlify anda:

  "$schema": "https://mintlify.com/schema.json",
  "name": "<your-documentation-title>",
  "logo": {
    "dark": "<logo-for-dark-mode>",
    "light": "<logo-for-light-mode>"
  },
  "favicon": "<link-to-a-favicon>",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },
</link-to-a-favicon></logo-for-light-mode></logo-for-dark-mode></your-documentation-title>

3. Tab dan sauh:
Tab dan sauh boleh digunakan untuk menyediakan bahagian mendatar dan menegak masing-masing dalam dokumentasi anda. Di bawah ialah contoh tab:

Di bawah ialah contoh sauh:

Tetapan untuk komponen ini dikendalikan oleh tab dan kekunci sauh.

4. Tetapan navigasi:
Bahagian ini membantu anda mengumpulkan halaman dalam dokumentasi anda. Ia adalah tatasusunan yang terdiri daripada kunci kumpulan dan tatasusunan halaman yang mana halaman untuk kumpulan itu ditambah secara berurutan. Di bawah ialah contoh cara ia ditambahkan:

git clone https://github.com/<your github username>/docs 
</your>

Tetapan di atas akan diterjemahkan kepada imej di bawah:

Halaman (pengenalan, dll.) ialah fail .mdx dalam folder dokumen projek anda.

5. Navigasi bersarang:
Navigasi bersarang biasanya digunakan untuk membuat subseksyen dalam dokumentasi. Di bawah ialah contoh navigasi bersarang:

Di bawah ialah contoh kod untuk menyediakan navigasi bersarang pada Mintlify:

npm i -g mintlify

Kod di atas menempatkan bahagian/kumpulan dalam bahagian lain. Kekunci ikon mencantikkan tajuk bahagian dengan ikon apabila dipaparkan pada halaman web.

6. Tetapan pengaki:
Kunci footerSocials digunakan untuk menambah akaun media sosial yang berkaitan dengan dokumentasi. Di bawah ialah contoh:

Bagaimana untuk menambah kandungan

Dokumentasi Mintlify membimbing anda tentang cara menambahkan kandungan pada dokumentasi anda. Saya syorkan anda menyemak dokumentasi untuk mengetahui cara menambahkan kandungan berbeza pada dokumentasi anda.

Lihat sampel dokumentasi ini untuk mendapatkan inspirasi tentang cara menstruktur dokumentasi anda sendiri.

Petua menulis dokumentasi

Di bawah ialah beberapa petua untuk membantu anda menulis dokumentasi yang jelas dan mesra pengguna:

1. Bersikap langsung yang mungkin: Elakkan maklumat luar yang tidak menambah nilai. Dokumentasi anda adalah untuk pembangun yang ingin menggunakan pakej atau alat anda dalam projek seterusnya mereka jadi hanya tunjukkan kepada mereka perkara yang mereka perlukan untuk mencapai ini.

2. Tambahkan penerangan atau gambaran keseluruhan alat anda:
Sebelum pergi ke butiran tentang cara menggunakan alat anda, terangkan secara ringkas apakah alat anda dan masalah yang diselesaikannya. Ini sepatutnya pada halaman pertama.

3. Tambahkan sampel kod yang mencukupi:
Ini akan membantu mereka memahami cara menggunakan alat anda tanpa ralat yang tidak perlu. Contoh kod pada pemasangan, pengesahan, sampel respons, hujah kaedah, dll adalah sangat penting.

4. Ralat dan pengecualian:
Ini akan membantu pengguna dalam penyahpepijatan. Tambahkan halaman untuk menerangkan jenis ralat yang mungkin dihadapi oleh pengguna semasa menggunakan alat anda. Tunjukkan juga sampel kod untuk ini.

Tolak projek ke Github

Ikuti langkah di bawah untuk menolak projek ke Github:

1. Buka terminal git bash dalam projek anda dan tukar ke folder dokumen dengan arahan di bawah:

git clone https://github.com/<your github username>/docs 
</your>

2. Alih keluar git daripada folder ini dengan arahan di bawah:

npm i -g mintlify

Arahan ini mengalih keluar .git daripada folder docs untuk mengelakkan isu apabila anda mahu menolak keseluruhan projek ke Github.

3. Tolak projek ke GitHub.

Sebarkan dokumentasi

Ikuti langkah di bawah untuk menggunakan dokumentasi anda pada Mintlify:
1. Log masuk ke papan pemuka Mintlify anda
2. Klik pada tab Tetapan

3. Tukar repo Mintlify Github anda kepada repo projek anda

4. Aktifkan suis monorepo. Ini menandakan bahawa folder dokumen wujud dalam projek lain dalam satu repo.

5. Masukkan **docs sebagai laluan ke fail mint.json dalam medan baharu yang muncul.**

6. Klik butang simpan untuk menyimpan perubahan.

Dokumentasi anda boleh diakses melalui pautan yang dipaparkan dalam tab gambaran keseluruhan papan pemuka anda

Mengemas kini Projek

Anda berkemungkinan besar membuat perubahan pada projek anda dan mungkin perlu mengatur semula projek itu.

Selepas membuat sebarang kemas kini dalam projek anda, pastikan anda menolak perubahan kepada Github. Mintlify secara automatik mengambil perubahan baharu dan mengemas kini dokumen anda dengan segera.

Kesimpulan

Dalam tutorial ini, anda mempelajari cara membina dokumentasi untuk perpustakaan Python menggunakan pendekatan docs-as-code.

Docs-as-code menggalakkan kerjasama dan penyepaduan berterusan pada projek. Mengenai sumber terbuka, docs-as-code membolehkan orang ramai bekerjasama dengan lancar dalam projek sambil mengekalkan dokumentasi yang betul dan terkini.

Terdapat API REST yang berbeza tanpa SDK atau perpustakaan pengaturcaraan. Pilih satu yang menarik minat anda dan buat sesuatu yang serupa.

Teruskan membina ?‍?!

Soalan Lazim

Bagaimanakah saya boleh menguji dokumentasi saya?

Ciri ini sering digunakan pada projek besar dengan berbilang penyumbang. Ujian dokumentasi dijalankan secara automatik apabila permintaan tarik dibuat kepada Projek. Jika ujian berjaya, perubahan akan digabungkan. Baca panduan ini tentang cara swimm menawarkan ujian dokumentasi automatik untuk mengetahui lebih lanjut.

Bolehkah saya meniru projek ini dalam bahasa pengaturcaraan lain?
Ya boleh. Ikuti prosedur dalam panduan ini untuk mendapatkan hasil yang serupa dalam bahasa pilihan anda.

Adakah terdapat tapak dokumentasi lain kecuali Mintlify?
Ya, terdapat tapak dokumentasi lain yang boleh anda gunakan. Sebahagian daripadanya termasuk: Gitbook, Readme, Docusaurus, dll.

Atas ialah kandungan terperinci Docs-as-code in action: Mendokumentasikan pustaka Python.. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!