Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- AboutCode
- Penulis teknis:
- ayansinha
- Nama proyek:
- Referensi untuk Opsi Command Line di Scancode-toolkit 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 ini saat ini tidak memiliki dokumentasi yang tepat untuk menjelaskannya dan hanya tersedia melalui tanda "--help" atau "-h". Proyek ini bertujuan untuk membuat dokumentasi lengkap yang menjelaskan:
[ 1. Semua Opsi yang tersedia melalui Command Line ]
- Sasaran: Daftar lengkap semua opsi yang memungkinkan melalui command line.
- Ringkasan Dasar: Pertama, opsi pemindaian default dibahas, dengan contoh output. Gambar/deskripsi singkat tentang cara melakukan pemindaian.
Selanjutnya, perilaku default ini berfungsi sebagai referensi tentang cara opsi lain mengubah pemindaian dan output.
Hal ini akan dibahas secara mendetail dan akan memuat informasi berikut seperti yang disebutkan di bagian berikutnya.
[ 2. Memulai Struktur Pembuatan Versi ]
- Sasaran: Memulai sistem pembuatan versi untuk mengelola perubahan opsi lintas-rilis/API dan dokumentasi dengan benar.
- Masalah: Saat ini dokumentasi di wiki dan halaman ReadTheDocs adalah untuk rilis lama dan perlu restrukturisasi besar.
- Ringkasan Dasar: Bagian dari toolkit kode pindai 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. Dokumentasi juga harus mengikuti, atau akan menyebabkan kebingungan besar bagi pengguna. Utilitas command line [ --help ] sudah diupdate 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 Pindai Kode-Toolkit yang menyediakan fungsi tersebut.
- Ringkasan Dasar: Bagian ini memberikan contoh skenario kasus penggunaan yang berbeda dan opsi yang direkomendasikan dalam skenario tersebut.
- Catatan: Bagian ini memerlukan bantuan yang signifikan dari mentor dalam hal masukan dan petunjuk ke berbagai kasus penggunaan Scancode-Toolkit.
[ 4. Yang berubah dari Opsi ini pada Pemindaian dan Hasil ]
- 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 ke 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: Alat Pemindaian memiliki tanda untuk menentukan format output yang berbeda tempat hasil pemindaian akan dihasilkan. Ini adalah -
Bagian ini akan - menjelaskan secara mendetail 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}. Hal ini juga tertaut ke 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 Pemindaian Dalam daftar ide GSoD, Format Output Pemindaian disebutkan sebagai ide referensi. Bagian ini mengimplementasikan hal yang sama.
- Catatan: Bagian ini memerlukan bantuan yang signifikan dari mentor dalam hal masukan dan petunjuk ke 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.
- Ringkasan Dasar:
- Scancode-Workbench Bagian ini menjelaskan cara memvisualisasikan hasil dengan aplikasi desktop dan pointer ke dokumentasi pindai kode-workbench untuk dukungan lebih lanjut terkait hal yang sama. Akan menambahkan dokumentasi yang diperlukan ke Scancode-workbench jika diperlukan.
- Deltacode Cara hasil pemindaian kode diambil oleh Deltacode untuk menentukan perbedaan level file antara dua codebase.
[ 2. Mengatur ulang struktur AboutCode Documentation ]
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 disebutkan. Hal yang sama diperlukan untuk bagian lain dari dokumentasi 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 kesalahan sintaks 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 Pull Request #17 ini) Kini memerlukan lebih banyak pemeriksaan untuk lint tertentu dalam reStructured Text dan standar lainnya. Hal ini dapat dicapai dengan lint teks yang disusun ulang, tetapi memerlukan lebih banyak penelitian dan akan dilakukan sebagai bagian dari project GSoD saya.
[ 3. Menambahkan Bagian “Memulai” ]
Ini akan bertindak sebagai bagian awal bagi para pendatang baru dan akan berisi kompilasi dokumen yang paling dasar dan penting untuk memulai Proyek {i>Aboutcode<i}. Setiap Project Aboutcode akan memiliki bagian ini, termasuk Scancode-Toolkit, Scancode-Workbench, Deltacode, dan lainnya.
[ 4. Restrukturisasi Sesuai dengan 4 Fungsi Dokumen ]
Dokumentasi yang ada tidak terstruktur secara eksplisit dalam 4 fungsi dokumen - Tutorial, Petunjuk, Referensi, dan Penjelasan. Saya mengusulkan untuk menyusunnya sesuai dengan persyaratan tersebut, dengan menambahkan lebih banyak informasi/penjelasan/pointer apa pun yang diperlukan. Ini berlaku untuk semua project AboutCode dan dokumentasinya. Di bawah ini adalah dua contoh restrukturisasi dokumentasi Scancode-Toolkit yang saya usulkan dan akan lanjutkan dalam proyek ini. Perubahan serupa akan dilakukan pada dokumentasi lainnya.
[ 5. Menyusun Ulang Laman Pengembangan (Scancode-Toolkit) ]
Info lebih lanjut terkait Kode/API dapat ditambahkan untuk menjadikannya lebih mudah digunakan oleh developer. Dapat terdapat link ke [ 2. Diskusi yang menjelaskan bagian Pemindaian Kode ] di atas. Tautan ini menjelaskan tentang cara kerja pemindaian ke kode yang digunakan untuk melakukan pemindaian. Seperti halnya folder ini berisi bagian-bagian berbeda dari toolkit pindai kode, penggunaannya masing-masing dapat dijabarkan dengan API, bersama dengan Diskusi tentang cara kerja kode pindai.
- [ hintscode : plugin untuk memindai lisensi, hak cipta, URL, email ]
- [commoncode : class bantuan dan fungsi]
- [ kode ekstrak : mengekstrak format arsip yang berbeda ]
- [formatcode : pemformatan output untuk format file output berbeda ]
- [Licensecode : kode deteksi lisensi ]
- [packagecode : menguraikan berbagai format paket ]
- [ plugincode : kelas untuk arsitektur plugin ]
- [ringkasankode : merangkum pemindaian pada lisensi yang terdeteksi ]
- [kode teks : menangani penguraian teks ]
- [ typecode : menangani penentuan jenis file ]
- [scancode : CLI dan API untuk memindai kode, bagian inti ]
Subbagian ini akan berisi informasi/API terperinci tentang 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. Menyusun ulang 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 yang terpisah secara terpisah.
- Bagaimana cara kerja ScanCode? Masalah ini dirujuk di [ 2. Pembahasan yang menjelaskan Pemindaian Kode ] dan akan menjadi bagian yang sepenuhnya terpisah dengan detail yang lebih lengkap.
- Bagaimana Cara Menambahkan Aturan Lisensi Baru untuk Deteksi yang Ditingkatkan? Masalah ini sudah dibahas sebelumnya dalam Meningkatkan Petunjuk yang sudah ada, dokumentasi akan dipindahkan ke sana.
- Bagaimana cara menambahkan aturan deteksi lisensi baru? Hal ini bisa dibuat menjadi postingan “How To” lain secara terpisah dan dapat dijabarkan.
- Bagaimana Cara mulai menggunakan Pengembangan? Sudah ada halaman pengembangan terpisah dan informasinya sering tumpang tindih. Restrukturisasi halaman pengembangan telah dibahas di atas.
- Langkah-langkah untuk memotong rilis baru Ini dapat diubah menjadi “How To Cut a new release”.
- Temukan lebih banyak pertanyaan FAQ yang menjawab pertanyaan umum tentang project dan tidak termasuk dalam kategori “Petunjuk”/”Tutorial”.