Halaman ini berisi detail proyek penulisan teknis yang diterima untuk Google Season of Dokumen.
Ringkasan proyek
- Organisasi open source:
- AboutCode
- Penulis teknis:
- ayansinha
- Nama proyek:
- Referensi untuk Opsi Command Line di toolkit pindaicode dan Mengatur ulang struktur dokumentasi AboutCode di aboutcode.readthedocs.io
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
[ 1. Opsi Baris Perintah Scancode-Toolkit ]
Scancode-Toolkit memiliki sejumlah opsi Command Line untuk menyesuaikan cara pemindaian dilakukan, format output, dan beberapa opsi lainnya seperti plugin pasca-pemindaian. Opsi tersebut saat ini tidak memiliki dokumentasi yang tepat untuk menjelaskannya dan hanya tersedia melalui flag "--help" atau "-h". Proyek ini bertujuan untuk membuat dokumentasi lengkap yang menjelaskan:
[ 1. Semua Opsi yang tersedia melalui Command Line ]
- Sasaran: Daftar lengkap dari semua opsi yang mungkin melalui command line.
- Ringkasan Dasar: Pertama, opsi pemindaian default akan dibahas, dengan contoh outputnya. Gambar/deskripsi singkat tentang cara pemindaian dilakukan.
Selanjutnya, perilaku default ini bertindak sebagai referensi tentang cara opsi lain mengubah pemindaian dan output.
Hal ini akan dibahas secara mendetail dan akan berisi informasi berikut seperti yang disebutkan di bagian selanjutnya.
[ 2. Memulai Struktur Pembuatan Versi ]
- Sasaran: Memulai sistem pembuatan versi untuk mempertahankan perubahan dokumentasi/opsi lintas-rilis dengan benar.
- Masalah: Saat ini dokumentasi di wiki dan halaman ReadTheDocs adalah untuk rilis lama dan membutuhkan restrukturisasi besar.
- Ringkasan Dasar: Bagian-bagian toolkit pemindaian kode yang telah diperbarui/dapat diperbarui dalam versi adalah
- Opsi Command Line
- API
- Dokumentasi (Untuk dimulai) Opsi command line dan API diubah dalam versi dan rilis, dan dokumentasi juga harus mengikuti, atau akan menyebabkan kebingungan besar bagi pengguna. Utilitas command line [ --help ] sudah diperbarui untuk setiap perubahan pada opsi dan dapat digunakan untuk mereplikasi pembuatan versi dalam dokumentasi.
[ 3. Bagaimana Opsi ini dapat digunakan dalam berbagai kasus ]
- Tujuan: Bagian ini akan memberikan ringkasan dasar tentang bagaimana hasil pemindaian toolkit kode pindai dapat digunakan dalam berbagai penyebab dan opsi Scancode-Toolkit yang menyediakan fungsi tersebut.
- Ringkasan Dasar: Bagian ini memberikan contoh skenario penggunaan yang berbeda dan opsi apa yang direkomendasikan dalam skenario tersebut.
- Catatan: Bagian ini membutuhkan bantuan yang signifikan dari mentor dalam hal masukan dan petunjuk untuk berbagai kasus penggunaan Scancode-Toolkit.
[ 4. Apa yang diubah oleh Opsi ini pada Pemindaian dan Output ]
- Tujuan: Bagian ini akan memberikan ringkasan dasar tentang bagaimana hasil pemindaian toolkit kode pindai dapat digunakan dalam berbagai penyebab, dan alat Aboutcode yang menyediakan fungsi tersebut.
- Ringkasan Dasar: Opsi ini mengubah perilaku cara pemindaian dilakukan. Kasus default dasar akan diilustrasikan di bagian awal [ 1. Semua Opsi yang tersedia melalui Command Line ] dan bagian ini akan membandingkan perubahan yang dihadirkan oleh semua opsi pada skenario default ini.
[ 5. Format Output dan contohnya ]
- Tujuan: Bagian ini akan memberikan ringkasan dasar tentang bagaimana hasil pemindaian toolkit kode pindai dapat digunakan dalam berbagai penyebab, dan alat Aboutcode yang menyediakan fungsi tersebut.
- Ringkasan Dasar: Scancode-Tool memiliki flag untuk menentukan format output yang berbeda yang akan menghasilkan hasil pemindaian. Ini adalah -
Bagian ini akan - menjelaskan secara detail format {i>output<i}
- berikan contoh format output
- memberikan tautan lain yang sesuai dengan format {i>output<i} dan penggunaannya
- bagaimana hasil pemindaian disimpan dalam file {i>output<i}. Penjelasan ini juga terkait dengan Bagaimana berbagai format ini dihasilkan, yang akan dijelaskan dalam [ 2. Pembahasan yang menjelaskan Pemindaian Kode ].
[ 6. Penggunaan Bisnis Format Output Kode Pemindaian ]
- Tujuan: Menjelaskan kasus Penggunaan Bisnis format Output Scancode Dalam daftar ide GSoD, Format Output Scancode disebutkan sebagai ide referensi. Bagian ini mengimplementasikan hal yang sama.
- Catatan: Bagian ini membutuhkan bantuan yang signifikan dari mentor dalam hal masukan dan petunjuk untuk berbagai kasus penggunaan bisnis Scancode-Toolkit.
[ 7. Bagaimana output ini digunakan oleh project AboutCode lainnya untuk analisis lebih lanjut ]
- Tujuan: Bagian ini akan memberikan ringkasan dasar tentang bagaimana hasil pemindaian toolkit kode pindai dapat digunakan dalam berbagai penyebab, dan alat Aboutcode yang menyediakan fungsi tersebut.
- Ikhtisar Dasar:
- Scancode-Workbench Bagian ini menjelaskan memvisualisasikan hasil dengan aplikasi desktop dan pointer ke dokumentasi pindaicode-workbench untuk dukungan lebih lanjut terkait hal yang sama. Akan menambahkan dokumentasi yang diperlukan untuk memindaicode-workbench jika diperlukan.
- Deltacode Cara hasil pemindaian kode diambil oleh Deltacode untuk menentukan perbedaan tingkat file antara dua codebase.
[ 2. Mengatur ulang struktur Dokumentasi AboutCode ]
Bagian ini mencakup sejumlah perubahan pada Dokumentasi Aboutcode
[ 1. Sistem pembuatan versi ]
Dalam [ 1. Opsi Baris Perintah Scancode-Toolkit -> 2. Memulai Struktur Pembuatan Versi], masalah pembuatan versi opsi Command Line telah disebutkan. Hal yang sama diperlukan untuk bagian dokumentasi lain yang juga berisi perintah/informasi khusus versi yang akan menimbulkan kebingungan.
[ 2. Menetapkan Standar dan Pengujian Dokumentasi ]
Dokumentasi sudah memiliki pengujian untuk spinx-build (membangun semua halaman dan memeriksa error sintaksis Sphinx secara keseluruhan) dan pemeriksaan link (Memeriksa semua link ke halaman web lain dari dokumentasi) dengan Continuous Integration melalui Travis-CI. (Ditambahkan oleh saya dalam Permintaan Pull #17 ini) Sekarang, diperlukan lebih banyak pemeriksaan untuk analisis lint tertentu dalam Teks Berstruktur ulang dan standar lainnya. Hal ini dapat dicapai dengan lint teks yang direstrukturisasi, tetapi membutuhkan lebih banyak riset dan akan dilakukan sebagai bagian dari project GSoD saya.
[ 3. Menambahkan Bagian “Memulai” ]
Ini akan bertindak sebagai bagian awal bagi pendatang baru dan akan berisi kompilasi dokumen paling dasar dan penting untuk memulai Project Aboutcode. Setiap Project Aboutcode akan memiliki bagian ini yang mencakup Scancode-Toolkit, Scancode-Workbench, Deltacode, dan lainnya.
[ 4. Restrukturisasi Sesuai dengan 4 Fungsi Dokumen ]
Dokumentasi yang ada tidak secara eksplisit terstruktur dalam 4 fungsi dokumen - Tutorial, Petunjuk, Referensi, dan Penjelasan. Saya mengusulkan untuk menyusunnya sesuai dengan itu, dengan menambahkan lebih banyak informasi/penjelasan/pointer apa pun yang diperlukan. Ini berlaku untuk semua project AboutCode dan dokumentasinya. Berikut adalah dua contoh restrukturisasi dokumentasi Scancode-Toolkit yang saya usulkan dan akan diterapkan dalam project ini. Perubahan serupa akan dilakukan pada dokumentasi lainnya.
[ 5. Menata Ulang Laman Pengembangan (Scancode-Toolkit) ]
Info lebih lanjut tentang Kode/API dapat ditambahkan untuk membuatnya lebih mudah digunakan oleh developer. Dapat berupa link ke [ 2. Diskusi yang menjelaskan bagian Pemindaian Kode ] di atas. Ini menautkan penjelasan tentang cara kerja pemindaian ke kode yang digunakan untuk melakukan pemindaian. Seperti folder-folder ini yang berisi berbagai bagian toolkit kode pindai, penggunaannya masing-masing dapat dijabarkan dengan API, bersamaan dengan Diskusi tentang cara kerja kode pindai.
- [Hintcode : plugin untuk memindai lisensi, hak cipta, URL, email ]
- [ commoncode : fungsi dan class bantuan]
- [ extractcode : mengekstrak format arsip yang berbeda ]
- [formatcode : pemformatan output untuk berbagai format file output ]
- [ berlisensi : kode deteksi lisensi ]
- [packagecode]: menguraikan berbagai format paket]
- [ plugincode : class untuk arsitektur plugin ]
- [ringkasancode : merangkum pemindaian pada lisensi yang terdeteksi ]
- [ kode teks : menangani penguraian teks ]
- [ typecode : menangani penentuan jenis file ]
- [ pindaicode : CLI dan API untuk memindai kode, bagian inti ]
Subbagian ini akan berisi informasi/API terperinci mengenai bagian-bagian toolkit kode pindai ini di sub-bagian yang sesuai. Pedoman pengembangan akan tersedia di halaman lain atau bagian lain yang memiliki subbagian yang lebih kecil.
[ 6. Mengubah struktur laman FAQ (Scancode-Toolkit) ]
Halaman FAQ saat ini memiliki pertanyaan yang dapat dijawab dengan lebih baik dan harus disusun sebagai dokumen Petunjuk, Tutorial, dan Referensi secara terpisah.
- Bagaimana cara kerja ScanCode? Masalah ini dirujuk dalam [ 2. Pembahasan yang menjelaskan Pemindaian Kode ] dan akan menjadi bagian yang sepenuhnya terpisah dengan lebih banyak detail.
- Bagaimana Cara Menambahkan Aturan Lisensi Baru untuk Deteksi yang Ditingkatkan? Masalah ini sudah dibahas sebelumnya dalam Meningkatkan Petunjuk yang ada, dokumentasi akan dipindahkan ke sana.
- Bagaimana cara menambahkan aturan deteksi lisensi baru? Hal ini bisa dibuat menjadi posting “{i>How To<i}” lain secara terpisah dan dapat dijabarkan.
- Bagaimana Cara mulai menggunakan Pengembangan? Sudah ada halaman pengembangan terpisah dan informasinya cukup banyak tumpang tindih. Restrukturisasi halaman pengembangan telah dibahas di atas.
- Langkah-langkah untuk memotong rilis baru Ini dapat diubah menjadi “Cara Memotong rilis baru” yang terpisah.
- Temukan pertanyaan FAQ lainnya yang menjawab pertanyaan umum tentang project dan tidak termasuk dalam kategori “Petunjuk”/”Tutorial”.