Readthedocs.org: Visi untuk MkDocs pada Baca Dokumen

• Search Indexing RTD menggunakan json builder (dihapus pada 0.17, lihat #4205) untuk mengindeks pencarian. Akan lebih baik untuk memiliki ini atau sesuatu seperti itu sebagai lawan dari merayapi/mengindeks HTML.

MkDocs masih menyediakan file JSON yang mencantumkan semua halaman dengan kontennya sebagai bagian dari plugin pencarian . Jelas, RTD tidak memerlukan lunr.js dan hal-hal pendukung, tetapi plugin dapat dikonfigurasi untuk hanya menyediakan data JSON. Yang mengatakan, konfigurasi dimaksudkan untuk didefinisikan dari dalam konfigurasi tema, jadi jika pilihan tema pengguna RTD honor, akan sulit untuk menimpa konfigurasi itu. Dan data JSON sebenarnya dipecah menjadi bagian header, bukan halaman lengkap, yang mungkin atau mungkin tidak berfungsi dengan implementasi pencarian Anda.

Namun, seharusnya tidak terlalu sulit untuk mengkloning bagian plugin yang relevan untuk tujuan RTD. Karena plugin dapat menyuntikkan ke dalam tema, Anda bahkan dapat menggunakan plugin Anda untuk mengganti template versions.html , atau untuk menambahkan JavaScript Anda sendiri, atau mod tema lain apa pun yang mungkin Anda perlukan. Dengan kata lain, saya percaya bahwa, dengan satu plugin, RTD dapat dengan mudah bekerja dengan tema MkDocs pihak ketiga mana pun selama Anda mendokumentasikan kait yang perlu disediakan oleh penulis tema. Lihat dokumen untuk detailnya.

Satu bagian yang sulit adalah memasukkan plugin Anda ke dalam konfigurasi. Secara default, pengaturan plugins yang tidak ditentukan (oleh pengguna) menghasilkan plugin search yang disertakan. Namun, jika ada plugin yang ditentukan pengguna disertakan, maka hanya plugin yang ditentukan pengguna yang digunakan (ini bukan aditif). Oleh karena itu, Anda harus berhati-hati agar tidak kehilangan plugin yang disertakan pengguna saat menambahkan plugin Anda. Kecuali jika pengguna secara eksplisit menyertakan search , Anda juga harus menghapusnya dari daftar.

• Stabilitas format Stabilitas dalam format mkdocs.yml terutama seputar tema. Ada beberapa perubahan mundur yang tidak kompatibel di sini dari 0.15.x ke 1.x. Karena RTD mendukung beberapa versi MkDocs, ini menjadi masalah. Ini mungkin bukan masalah setelah kami berhenti mengganti tema.

Dipahami. Namun, perubahan yang tidak kompatibel ke belakang itu adalah bagian dari pengembangan pra 1.0. Sekarang setelah 1.0 dirilis, kami bermaksud untuk menjaga stabilitas di seluruh seri 1.x (2.0 belum ada di peta jalan kami). Perubahan di masa mendatang harus bersifat aditif dan terus bekerja dengan format konfigurasi yang ada.

Hal-hal yang dibutuhkan MkDocs dari RTD

Selain item yang tercantum di atas, kami juga membutuhkan:

• Dokumentasi yang jelas tentang apa RTD bergantung pada . Idealnya, akan ada satu lokasi yang akan mencantumkan semua kait/API yang digunakan RTD. Misalnya, jika daftar seperti itu ada, kami mungkin tidak menghapus pembuat json , karena kami mendapat kesan bahwa itu tidak digunakan. Ya, informasi ini tersedia dengan membaca kode, tetapi itu tidak praktis setiap kali kita perlu melakukan pemeriksaan cepat. Perhatikan bahwa dokumentasi yang diminta bukan untuk pengguna akhir, tetapi untuk pengembang MkDocs, pengembang Tema, dan mungkin pengembang plugin. Ini mungkin tidak sesuai dengan dokumentasi publik Anda, jadi halaman wiki atau sejenisnya akan baik-baik saja.

Masalah ini secara otomatis ditandai sebagai basi karena tidak ada aktivitas terbaru. Ini akan ditutup jika tidak ada aktivitas lebih lanjut yang terjadi. Terima kasih atas kontribusi Anda.

@waylan terima kasih, maaf atas balasan yang sangat terlambat. Kami sekarang berfokus pada peningkatan pengalaman MkDocs di RTD, kami akan mengindeks data pencarian dari file search/search_index.json . Jadi alangkah baiknya jika ada perubahan pada struktur file itu akan di-kipped atau diversi jika ada perubahan. Saya akan menulis dokumen yang Anda sebutkan dalam beberapa hari/minggu ke depan.