Dalam artikel ini, saya akan membimbing anda langkah demi langkah untuk mencipta tapak dokumentasi dinamik, boleh disesuaikan dengan mana-mana projek, di mana anda boleh menyambungkan dokumentasi anda ke pangkalan data untuk mengekstrak dan memaparkan data, memastikan maklumat sentiasa terkini. Kami juga akan meneroka cara untuk mengautomasikan keseluruhan proses, daripada penjanaan kandungan hingga penggunaan dalam awan dengan AWS.

Penyelesaian termasuk sokongan untuk carta dan gambar rajah, penyepaduan berterusan (CI/CD) menggunakan aliran kerja mudah dalam Tindakan GitHub dan penggunaan automatik menggunakan Terraform. Mari mulakan!

Apakah Dokumentasi sebagai Kod?

Dokumentasi dan kemas kininya merupakan proses penting dalam banyak syarikat yang membangunkan perisian, selalunya dijalankan menggunakan alat yang berbeza, kebanyakannya adalah penyelesaian berbayar.

Oleh itu, sejak kebelakangan ini, konsep "doc as code" telah muncul. Ini bermakna menggunakan alatan dan aliran kerja yang sama yang digunakan dalam pembangunan perisian untuk mengurus, versi dan menggunakan dokumentasi.

Pendekatan ini bukan sahaja membolehkan penjejakan dokumentasi yang lebih baik tetapi juga memudahkan penyelenggaraannya dan memastikan penjajaran dengan amalan terbaik yang sama yang digunakan dalam pembangunan perisian, bukan sahaja dalam kod tetapi juga dalam dokumentasi.

Alat untuk Dokumentasi sebagai Kod

Untuk pembangunan tapak ini, adalah penting untuk memahami beberapa amalan dan alatan yang membolehkan kami melaksanakan pendekatan ini. Di bawah ialah senarai terperinci aspek yang paling penting untuk diliputi dalam tutorial ini.

• ? Markdown: Bahasa penanda yang paling biasa untuk menulis dokumentasi kerana kesederhanaan dan penyepaduan dengan platform kawalan versi dan penjana tapak statik.
• ?️ Git: Git membenarkan versi dokumentasi sama seperti kod. Terima kasih kepada Git, setiap perubahan dalam dokumentasi direkodkan, membolehkan pasukan menjejak suntingan, mengembalikan perubahan dan bekerjasama dengan lebih cekap.
• ? Gitflow: Metodologi ini menyediakan aliran kerja berstruktur untuk mengurus versi dan semakan dokumentasi, memastikan perubahan diluluskan dan diuji sebelum mencapai pengeluaran. Gitflow turut memudahkan kerjasama antara pasukan, membolehkan pengurusan perubahan yang selamat dan teratur.
• ☁️ Perkhidmatan Cloud: Menggunakan perkhidmatan seperti AWS S3, Netlify atau Halaman GitHub, anda boleh menggunakan dokumentasi pada kos yang rendah. Perkhidmatan ini membolehkan penciptaan tapak statik yang pantas, selamat dan mudah diakses.
• ? Penjana Tapak Statik: Alat seperti Docusaurus, Jekyll atau Hugo menukar dokumentasi Markdown menjadi tapak web yang boleh dilayari, membolehkan anda membuat dokumentasi yang kaya dan teratur tanpa pelayan.
• ? Integrasi Berterusan (CI/CD): Saluran paip CI/CD (cth., GitHub Actions, GitLab CI atau Jenkins) membolehkan anda menggunakan dokumentasi secara automatik apabila versi baharu digabungkan atau pengubahsuaian diluluskan. Ini memastikan dokumentasi sentiasa terkini.

Kelebihan Docs-as-Code

• ✅ Ketekalan dan Kualiti: Dengan menggunakan kawalan versi dan semakan perubahan, dokumentasi kekal konsisten dan berkualiti tinggi.
• ⚙️ Automasi: Alat CI/CD membolehkan automasi pelaksanaan dokumentasi, mengurangkan masa kemas kini dan meminimumkan ralat.
• ? Kerjasama Cekap: Dengan alatan seperti Git, pasukan boleh bekerjasama dalam mencipta dan mengekalkan dokumentasi tanpa konflik.
• ? Penyelenggaraan Ringkas: Penyelenggaraan dokumentasi disepadukan ke dalam aliran kerja pembangunan, menjadikan kemas kini lebih mudah apabila kod berkembang.

? MkDocs

MkDocs ialah penjana tapak statik yang ditulis dalam ?Python, direka khusus untuk mendokumentasikan projek. Matlamatnya adalah untuk memudahkan membuat dokumentasi menggunakan fail Markdown, yang mudah ditulis dan dibaca.

Dengan konfigurasi minimum, MkDocs menukarkan fail Markdown menjadi tapak web dokumentasi yang boleh dilayari dan tersusun dengan baik, menjadikannya sesuai untuk pembangun dan pasukan yang ingin memastikan dokumentasi mereka dikemas kini.

✏️ Bahan MkDocs

Bahan MkDocs ialah tema lanjutan untuk MkDocs yang mengikut garis panduan Reka Bentuk Bahan Google.

? Ciri-ciri utama termasuk:

• ? Reka Bentuk Responsif: Secara automatik menyesuaikan diri dengan mana-mana saiz skrin.
• ? Penyesuaian: Ubah suai warna, fon, favicon dan logo dengan mudah untuk dipadankan dengan identiti visual projek anda.
• ? Antara Muka Carian: Hasil kumpulan carian terperinci dan menyerlahkan istilah carian, membantu pengguna mencari maklumat yang mereka perlukan.
• ⚡ Lazy Loading: Melaksanakan pemuatan malas untuk hasil carian, meningkatkan prestasi dan mengurangkan masa muat.
• ? Integrasi: Serasi dengan Google Analitis, Disqus dan GitHub, memudahkan analisis trafik, maklum balas pengguna dan sambungan terus ke repositori projek.

✏️ Duyung

Mermaid ialah pustaka JavaScript untuk mencipta rajah dan carta daripada teks. Dengan menyepadukan dengan Bahan MkDocs, Mermaid membolehkan anda menjana visualisasi seperti carta alir, rajah perhubungan entiti dan carta lain dalam dokumentasi tanpa alat luaran.

? Halaman Dinamik: Jinja

Jinja ialah perpustakaan yang membenarkan membenamkan pembolehubah dan data daripada kamus Python ke dalam HTML, menjadikan halaman web dinamik. Pustaka ini biasanya digunakan untuk menjana HTML dinamik dan menghantar e-mel yang diperibadikan.

? Gambaran Keseluruhan Docusaurus

Docusaurus ialah projek sumber terbuka yang dibangunkan oleh Meta pada tahun 2007 yang memudahkan penciptaan, penggunaan dan penyelenggaraan tapak web dokumentasi dengan cara yang pantas dan cekap. Ia membenarkan penggunaan Markdown dan MDX untuk menulis kandungan, manakala terasnya yang dibina pada React membolehkan penyesuaian penuh gaya untuk memenuhi keperluan khusus projek.

Selain itu, Docusaurus menyokong Mermaid melalui pemalam @docusaurus/theme-mermaid, membolehkan kemasukan carta dan rajah terus dalam dokumentasi.

? Rajah sebagai Kod

Rajah sebagai Kod ialah pendekatan yang membolehkan anda membuat gambar rajah melalui kod, dan bukannya menggunakan alat grafik tradisional. Daripada membina gambar rajah secara manual, anda menulis kod dalam fail teks untuk menentukan struktur, komponen dan sambungan gambar rajah anda.

Kod ini kemudiannya diterjemahkan ke dalam imej grafik, menjadikannya lebih mudah untuk disepadukan dan didokumenkan dalam projek perisian. Ia amat berguna untuk mencipta dan mengemas kini gambar rajah seni bina dan aliran secara pengaturcaraan.

? Rajah sebagai Kod: Contoh Mencipta Rajah Awan

Seperti yang dinyatakan sebelum ini, Rajah membolehkan anda menjana pelan tindakan menggunakan ikon teknologi awan utama. Perwakilan gambar rajah ini dilakukan melalui nod dan dalam contoh kami, kami akan menggunakan semua nod dan perkhidmatan AWS yang berkaitan dengan awan.

Untuk butiran lanjut tentang cara saya mencipta ini, anda boleh membaca artikel saya tentang Diagram as Code, dan pelaksanaan penuh boleh didapati dalam repositori ini:

? Kes Penggunaan: Mencipta Tapak Dokumentasi untuk Projek Pembelajaran Mesin

Dalam kes penggunaan ini, saya akan membuat tapak dokumentasi untuk projek pembelajaran mesin yang melibatkan ? data hospital. Matlamatnya adalah untuk membina tapak dokumentasi interaktif menggunakan MkDocs pada mulanya dan kemudian memindahkannya ke Docusaurus. Tapak ini akan merangkumi komponen statik dan dinamik untuk memenuhi keperluan khusus, seperti membenamkan gambar rajah visual dan mengemas kini data secara dinamik daripada pangkalan data SQLite.

? Ciri-ciri Utama Tapak Dokumentasi

1. Perwakilan Visual: Saya akan membenamkan gambar rajah yang dibuat dengan Gambar rajah (Rajah sebagai Kod) untuk menggambarkan seni bina saluran paip pembelajaran mesin dengan berkesan.
2. Kemas Kini Data Dinamik: Dokumentasi akan memaparkan versi dan tarikh kemas kini terakhir secara dinamik, menarik maklumat ini daripada pangkalan data SQLite untuk memastikan ketepatan dan perkaitan.
3. Sampel data: Dokumentasi akan menyertakan sampel daripada jadual pesakit Syntha, yang mempamerkan data sintetik sebagai contoh.

? Halaman Laman

Atas sebab ini tapak dokumentasi kami akan mempunyai halaman berikut:

• ? Laman Utama: Halaman utama dokumentasi.
• ? Jadual:Penjelasan tentang jadual data Syntha dan kegunaannya.
• ? Seni Bina:Tinjauan keseluruhan terperinci tentang seni bina pemprosesan data, dihoskan pada AWS.
• ? Glosari: Glosari istilah yang digunakan sepanjang projek

Pelaksanaan MkDocs

Dalam bahagian ini, kami akan melalui langkah-langkah untuk menyediakan projek dokumentasi menggunakan MkDocs dari awal dan menerangkan struktur direktori tersusunnya.

? Prasyarat untuk MkDocs

Untuk bermula, anda perlu memasang pustaka ?Python berikut:

Pasang MkDocs dan Bahannya

  pip install mkdocs mkdocs-material

Pasang perpustakaan tambahan untuk membolehkan pengemaskinian kandungan dinamik

  pip install aiosql pandas sqlite3 jinja2 shutil

? Mkdocs: Penyediaan Projek

Mulakan Projek

Mulakan dengan mencipta projek MkDocs baharu. Jalankan arahan berikut dalam terminal anda:

   mkdocs new mkdocs
   cd mkdocs

Arahan ini mencipta projek MkDocs asas dengan struktur lalai.

Terokai Struktur Direktori

Setelah tapak MkDocs dibuat, anda perlu menambah fail dan folder berikut, kerana ia tidak disertakan secara lalai. 
Ingat, pautan ke repositori disediakan pada penghujung siaran ini untuk rujukan anda, dan setiap komponen akan diterangkan secara terperinci di bawah.

  pip install mkdocs mkdocs-material

?Mkdocs: Gambaran Keseluruhan Komponen

? Mkdocs: Mengkonfigurasi mkdocs.yml

Setelah kami menyediakan struktur projek kami, kami akan mengkonfigurasinya langkah demi langkah, bermula dengan fail mkdocs.yml. Fail ini mentakrifkan struktur dan tetapan untuk tapak dokumentasi anda. Begini cara ia harus distrukturkan:

mkdocs.yml

  pip install mkdocs mkdocs-material

Dalam fail konfigurasi ini, anda boleh melihat terutamanya dalam bahagian nav halaman yang boleh diakses daripada menu. Kemudian, kami menentukan sambungan Mermaid, yang akan diterangkan dalam bahagian seterusnya. Akhir sekali, bahagian tema menggunakan tema Bahan, membolehkan penggayaan dan komponen tersedia dalam pustaka ini.

✏️ Mkdocs: Sambungan Duyung

Seperti yang dinyatakan sebelum ini, Mermaid ialah pustaka JavaScript untuk mencipta rajah dan carta daripada teks. Di bawah, kita akan melihat beberapa contoh. Dalam kes kami, kami akan menggunakannya untuk menjana Rajah Perhubungan Entiti (ERD) pada halaman jadual dokumentasi.

Dalam repositori, anda akan dapat melihat cara membina kod ini berdasarkan Rajah Perhubungan Entiti (ERD) yang terdapat dalam dokumentasi rasmi Synthea. Anda juga boleh menyemak contoh halaman jadual dalam pautan berikut: tables.md.

⚙️ Mkdocs: Kandungan Dinamik dengan Jinja

Untuk mendayakan penjanaan kandungan dinamik untuk tapak dokumentasi kami, kami akan menggunakan Jinja untuk memproses templat dan menggantikan ruang letak dengan data sebenar. Di bawah ialah pecahan langkah demi langkah:

1. Sediakan Folder templat
   
   Buat folder bernama templat untuk menyimpan semua fail Markdown untuk tapak. Fail ini harus mengandungi ruang letak. Sebagai contoh, dalam index.md, anda mungkin mempunyai ruang letak seperti {{database.version_date}} dan {{database.version}}.

2. Gunakan Pemegang Tempat
   
   Pemegang tempat ialah pembolehubah dinamik dalam fail Markdown. Pembolehubah ini akan dikemas kini secara automatik menggunakan kamus Python untuk menyuntik data yang berkaitan.

3. Jana Kandungan Dinamik dengan update.py

   • Sediakan templat Markdown anda dengan mengenal pasti bahagian yang memerlukan data dinamik.
   • Gunakan skrip Python (update.py), tersedia dalam repositori saya, untuk memproses templat. Skrip melaksanakan tugas berikut:
     • Sambungan Pangkalan Data: Menyambung ke pangkalan data SQLite untuk mengambil nilai terkini.
     • Rendering Templat: Menggunakan perpustakaan Jinja untuk menggantikan ruang letak dengan data daripada pangkalan data.
     • Penjanaan Fail: Mengeluarkan fail Markdown yang dikemas kini ke folder dokumen, sedia untuk dipapar dalam MkDocs.

  pip install mkdocs mkdocs-material

  pip install aiosql pandas sqlite3 jinja2 shutil

Dengan mengikut langkah ini, anda boleh mengautomasikan proses pengemaskinian untuk tapak dokumentasi anda, memastikan kandungan kekal dinamik dan relevan tanpa suntingan manual.

Kemas Kini Dinamik Jadual Data

Dalam contoh seterusnya, kami akan mengemas kini kandungan dalam fail tables.md untuk menunjukkan contoh jadual orang daripada pangkalan data. Untuk melakukan ini, kami akan mencipta pemegang tempat {{table.person}} dalam fail Markdown. Ideanya ialah untuk mengambil data secara dinamik daripada jadual orang, kemudian gunakan pustaka Jinja bersama-sama dengan panda untuk menukar hasil pertanyaan kepada format jadual Markdown.

Berikut ialah contoh bagaimana fail tables.md kelihatan dengan pemegang tempat:

   mkdocs new mkdocs
   cd mkdocs

Prosesnya adalah seperti berikut:

1. Soal Pangkalan Data: Skrip akan menanyakan jadual orang dalam pangkalan data SQLite untuk mengambil rekod yang berkaitan.
2. Tukar kepada Markdown: Menggunakan pandas, hasil pertanyaan akan ditukar kepada format jadual Markdown.
3. Ganti Pemegang Tempat: Pemegang tempat {{table.person}} dalam fail tables.md akan digantikan dengan jadual Markdown yang dijana.

   ? docs/
     ├── ? img/
     ├── `architecture.md`
     ├── `glossary.md`
     ├── `index.md`
     ├── `tables.md`
     ├── ? template/
     │   ├── ? db/
     │   │   ├── ? data/
     │   │   │   ├── hospital.db
     │   │   ├── ? queries/
     │   ├── `architecture.md`
     │   ├── `glossary.md`
     │   ├── `index.md`
     │   ├── `tables.md`
     │   └── `update.py`
   ? infraestructure/
   ? github/
     ├── ? workflows/
     │   ├── main.yml
   ? mkdocs.yml

Dengan cara ini, dokumentasi sentiasa mencerminkan data terkini, memaparkan contoh dinamik berdasarkan kandungan sebenar daripada pangkalan data.

⚙️ Mkdocs: Aliran Kerja Akhir

1. Buat Templat: Bangunkan halaman anda dalam direktori dokumen/templat.
2. Jalankan update.py: Isi kandungan dinamik dan jana fail akhir dalam dokumen/output.
3. Pratonton Setempat: Gunakan perkhidmatan mkdocs untuk pratonton tapak pada localhost.
4. Bina untuk Deployment: Gunakan binaan mkdocs untuk menjana tapak statik dalam folder docs/.
5. Gunakan: Gunakan Terraform untuk menggunakan tapak ke baldi AWS S3. Rujuk bahagian penempatan siaran ini untuk arahan terperinci.

? Pelaksanaan Docusaurus

Dalam bahagian berikut, saya akan memberikan langkah dan pandangan terperinci tentang cara melaksanakan tapak dokumentasi menggunakan Docusaurus. Ini termasuk pilihan persediaan, penyesuaian dan penggunaan.

? Ciri-ciri Utama Docusaurus

• ? Sokongan Mermaid: Sama seperti MkDocs, Docusaurus menyokong Mermaid untuk membenamkan gambar rajah.
• ⚛️ Komponen React: Dibina pada React, Docusaurus mendayakan penyepaduan komponen dinamik ke dalam dokumentasi anda.
• ? Kandungan Dinamik: Memanfaatkan skrip Python untuk mengambil dan mengemas kini kandungan secara dinamik daripada pangkalan data SQLite.

? Persediaan Docusaurus: Dari Gores

Untuk bermula dengan Docusaurus, kami mengikuti proses persediaan pantas, yang hampir sama dengan langkah yang kami gunakan untuk MkDocs tetapi dengan alatan yang berbeza.

1. Buat Projek Docusaurus Baharu: Mula-mula, pasang Node.js dan jalankan arahan berikut untuk mencipta tapak Docusaurus baharu:

  pip install mkdocs mkdocs-material

1. Pasang Pakej Mermaid: Untuk mendayakan gambar rajah Mermaid, pasang pakej yang diperlukan:

  pip install aiosql pandas sqlite3 jinja2 shutil

1. Jalankan Pelayan Pembangunan: Setelah dipasang, navigasi ke direktori projek anda dan jalankan pelayan pembangunan:

   mkdocs new mkdocs
   cd mkdocs

1. Lawati Tapak: Tapak anda akan disiarkan secara setempat di: http://localhost:3000.

? Penyesuaian Docusaurus: Konfigurasi

Fail konfigurasi docusaurus.config.js ialah tempat kami menyesuaikan tajuk, tema, navigasi dan mendayakan ciri seperti Mermaid untuk pemaparan rajah.
Contoh coretan untuk mendayakan Mermaid:

  pip install mkdocs mkdocs-material

? Docusaurus Menyesuaikan Halaman Utama

Untuk menyesuaikan halaman utama, kami mengubah suai fail src/components/HomepageFeatures/index.js. Di sini, anda boleh melaraskan objek FeatureList untuk mengemas kini ciri yang dipaparkan pada halaman utama.

? Organisasi dan Struktur Kandungan Docusaurus

Sama seperti dalam MkDocs, Docusaurus menyokong Fail Markdown untuk kandungan, dan kami menyusun struktur seperti berikut:

1. Folder Templat: Simpan fail Markdown anda dalam direktori dokumen/templat dan buat skrip Python (serupa dengan update.py) untuk mengambil dan mengisi data dinamik ke dalam templat ini.
2. Fail Kategori (__category__.json): Untuk mengurus susunan dokumen dalam bar sisi, cipta fail __category__.json dalam setiap folder. Contohnya:

  pip install aiosql pandas sqlite3 jinja2 shutil

__category__.json Contoh:

   mkdocs new mkdocs
   cd mkdocs

⚙️ Data Dinamik dengan Jinja

Untuk memasukkan kandungan dinamik, seperti jadual pangkalan data, kami menggunakan skrip ?Python bernama update.py, yang boleh anda temui dalam repositori.

Skrip ini mengambil data daripada pangkalan data SQLite dan memproses fail Markdown yang disimpan dalam folder templat. Ia kemudian mengemas kini fail ini dengan data yang diambil dan menyalinnya ke dalam folder dokumen, menyediakannya untuk pemaparan tapak.

Aliran kerja ini memastikan kandungan kekal terkini dan sedia untuk digunakan, mengikut pendekatan yang serupa dengan apa yang kami laksanakan dengan MkDocs.

⚙️ Docusaurus: Aliran Kerja Akhir

1. Buat Templat: Bangunkan fail Markdown anda dalam direktori dokumen/templat.
2. Jalankan Skrip Python: Gunakan skrip untuk mengisi data secara dinamik ke dalam templat.
3. Pratonton Setempat: Jalankan npx docusaurus mula untuk pratonton tapak.
4. Bina untuk Deployment: Setelah bersedia, gunakan npx docusaurus build untuk menjana tapak statik.
5. Sebarkan: Hos fail statik pada platform pilihan anda, seperti AWS S3.

? Kerahan

Dalam bahagian ini, kami akan merangkumi proses penggunaan untuk kedua-dua MkDocs dan Docusaurus menggunakan AWS S3 untuk pengehosan. Walaupun langkah penggunaan adalah sama untuk kedua-dua alatan, proses pemasangan berbeza, dengan MkDocs berasaskan Python dan Docusaurus berasaskan JavaScript.

Persediaan Infrastruktur dengan Terraform

Untuk menggunakan tapak dokumentasi statik ke AWS S3, kami menggunakan Terraform untuk menyediakan dan mengkonfigurasi sumber yang diperlukan. Persediaan mentakrifkan baldi S3, mendayakan pengehosan tapak web statik dan mengkonfigurasi akses awam dengan dasar baldi untuk membenarkan akses baca sahaja. Anda boleh mencari fail main.tf dalam repositori.

? Komponen Utama untuk Penggunaan S3

1. Penciptaan Baldi S3: Sumber untuk mencipta baldi S3 di mana dokumentasi akan dihoskan.
2. Penghosan Laman Web Statik: Konfigurasi untuk pengehosan web statik, menetapkan index.html dan error.html sebagai dokumen utama dan ralat.
3. Konfigurasi Akses Awam: Menguruskan akses awam kepada baldi S3, memastikan ia dikonfigurasikan untuk akses baca sahaja.
4. Dasar Baldi: Membenarkan akses awam untuk mendapatkan semula kandungan dokumentasi daripada baldi S3.

Anda boleh mengakses fail Terraform yang lengkap dan konfigurasi yang sepadan untuk mengatur letak tapak dalam repositori:

Fail Konfigurasi Terraform:

• fail mkdocs
• fail documentaurus

Aliran Kerja Tindakan GitHub untuk Penerapan Automatik: Saluran paip CI/CD untuk mengautomasikan proses penempatan turut disertakan dalam repositori.

• fail mkdocs
• fail documentaurus

Konfigurasi Tindakan GitHub
Pastikan untuk mengkonfigurasi bukti kelayakan AWS anda dalam Rahsia repositori GitHub di bawah Tetapan > Rahsia > Tindakan. Ini akan membolehkan GitHub Actions mengakses akaun AWS anda dengan selamat dan melakukan tindakan seperti memuat naik fail ke S3 apabila anda menolak perubahan pada cawangan utama.

Repositori

Di bawah ialah pautan kepada semua kod untuk menggunakan tapak dokumentasi anda. Jika anda rasa ia berguna, anda boleh tinggalkan bintang ⭐️ dan ikuti saya untuk menerima pemberitahuan artikel baharu. Ini akan membantu saya berkembang dalam komuniti teknologi dan mencipta lebih banyak kandungan.

• Pengedaran MkDocs: Repositori GitHub untuk MkDocs

• Pengedaran Docusaurus: Repositori GitHub untuk Docusaurus

? Kesimpulan Akhir: MkDocs lwn Docusaurus

Kedua-dua penyelesaian adalah mudah untuk dilaksanakan, tetapi dalam item berikut, kita boleh meneroka beberapa perbezaan dan apakah penyelesaian terbaik bergantung pada konteks, pengetahuan dan kerumitan yang mungkin anda perlu laksanakan.

• ? Bahasa & Penyesuaian: MkDocs adalah berasaskan Python, dengan konfigurasi dan templat YAML yang ringkas, sesuai untuk persediaan pantas. Sebaliknya, Docusaurus berasaskan React, menawarkan penyesuaian lanjutan dan komponen interaktif, menjadikannya lebih sesuai untuk pengguna yang memerlukan lebih kawalan ke atas visual.
• ? Penurunan Nilai & Rendering: Kedua-duanya menggunakan Markdown, tetapi Docusaurus membenarkan elemen interaktif, menjadikannya lebih baik untuk kandungan dinamik.
• ⚙️ Kerumitan: Docusaurus lebih baik untuk aplikasi dokumentasi yang kompleks, seperti yang mempunyai sistem log masuk. MkDocs lebih ringkas tetapi Docusaurus menawarkan lebih fleksibiliti untuk penggayaan dan ciri.
• ? Komuniti: Docusaurus mempunyai komuniti yang kuat dengan Discord dan 74 pemalam, manakala MkDocs bergantung pada perbincangan GitHub untuk sokongan komuniti.
• ☁️ Pengedaran Amazon: Anda boleh menggunakan tapak statik ke S3, mengurangkan kos penggunaan dan juga menggunakan CI/CD untuk penggunaan automatik.

? Rujukan

1. Mkdocs: https://www.mkdocs.org/
2. Mkdocs-Material: https://squidfunk.github.io/mkdocs-material/
3. Rajah: https://diagrams.mingrammer.com/
4. Docusaurus: https://docusaurus.io/
5. Jinja: https://jinja.palletsprojects.com/en/stable/
6. Buku Git - Apakah itu dokumen sebagai kod: https://www.gitbook.com/blog/what-is-docs-as-code
7. Tulis dokumen: https://www.writethedocs.org/guide/docs-as-code/

Atas ialah kandungan terperinci Meletakkan Docs-as-Code pada AWS: Membina Tapak Dokumentasi Dinamik dalam MkDocs dan Docusaurus. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!