Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- 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 project:
- Durasi standar (3 bulan)
Project description
[ 1. Opsi Command Line 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 flag “--help” atau “-h”. Project ini bertujuan untuk membuat dokumentasi lengkap yang menjelaskan:
[ 1. Semua Opsi yang tersedia melalui Command Line ]
- Sasaran: Daftar lengkap semua kemungkinan opsi melalui command line.
- Ringkasan Dasar: Pertama, opsi pemindaian default akan dibahas, dengan contoh output. Gambar/deskripsi singkat tentang cara pemindaian dilakukan.
Selanjutnya, perilaku default ini berfungsi sebagai referensi untuk cara opsi lain mengubah pemindaian dan output.
Hal ini akan dibahas secara mendetail dan akan berisi informasi berikut seperti yang disebutkan di bagian berikutnya.
[ 2. Memulai Struktur Pembuatan Versi ]
- Sasaran: Memulai sistem pembuatan versi untuk mempertahankan perubahan dokumentasi dan API/opsi lintas rilis dengan benar.
- Masalah: Saat ini, dokumentasi di wiki dan halaman ReadTheDocs ditujukan untuk rilis lama dan memerlukan penyusunan ulang besar-besaran.
- Ringkasan Dasar: Bagian-bagian toolkit pemindai kode yang telah diupdate/dapat diupdate dalam versi tersebut adalah
- Opsi Command Line
- API
- Dokumentasi (Akan dimulai) Opsi command line dan API diubah dalam versi dan rilis, dan dokumentasi juga harus mengikuti, atau akan menimbulkan kebingungan besar bagi pengguna. Utilitas command line [ --help ] sudah diupdate untuk setiap perubahan opsi dan dapat digunakan untuk mereplikasi pembuatan versi dalam dokumentasi.
[ 3. Bagaimana Opsi ini dapat digunakan dalam berbagai kasus ]
- Sasaran: Bagian ini akan memberikan ringkasan dasar tentang cara hasil pemindaian scancode-toolkit dapat digunakan dalam berbagai penyebab dan opsi Scancode-Toolkit yang menyediakan fungsi tersebut.
- Ringkasan Dasar: Bagian ini memberikan berbagai contoh skenario kasus penggunaan dan opsi yang direkomendasikan dalam skenario tersebut.
- Catatan: Bagian ini memerlukan bantuan yang signifikan dari mentor dalam hal input tentang dan pointer ke berbagai kasus penggunaan Scancode-Toolkit.
[ 4. Apa yang diubah Opsi ini dalam Pemindaian dan Output ]
- Sasaran: Bagian ini akan memberikan ringkasan dasar tentang cara hasil pemindaian scancode-toolkit dapat digunakan dalam berbagai penyebab, dan alat Aboutcode yang menyediakan fungsi tersebut.
- Ringkasan Dasar: Opsi ini mengubah perilaku pemindaian. Kasus default dasar akan diilustrasikan di bagian awal [ 1. Semua Opsi yang tersedia melalui Command Line ] dan bagian ini akan membandingkan perubahan yang dihasilkan oleh semua opsi pada skenario default ini.
[ 5. Format Output dan contohnya ]
- Sasaran: Bagian ini akan memberikan ringkasan dasar tentang cara hasil pemindaian scancode-toolkit dapat digunakan dalam berbagai penyebab, dan alat Aboutcode yang menyediakan fungsi tersebut.
- Ringkasan Dasar: Scancode-Tool memiliki flag untuk menentukan berbagai format output yang akan menampilkan hasil pemindaian. Ini adalah -
Bagian ini akan - menjelaskan secara rinci format {i>output<i}
- memberikan contoh format output
- memberikan link lain yang sesuai dengan format output dan penggunaannya
- cara hasil pemindaian disimpan dalam file output. Link ini juga terhubung ke Bagaimana format yang berbeda ini dibuat, yang akan dijelaskan dalam [ 2. Diskusi yang menjelaskan Pemindaian Kode ].
[ 6. Penggunaan Bisnis Format Output Kode Sandi ]
- Sasaran: Jelaskan Kasus Penggunaan Bisnis untuk Format Output Scancode Dalam daftar ide GSoD, Format Output Scancode disebutkan sebagai ide referensi. Bagian ini menerapkan hal yang sama.
- Catatan: Bagian ini memerlukan bantuan yang signifikan dari mentor dalam hal input tentang dan petunjuk ke berbagai kasus penggunaan bisnis Scancode-Toolkit.
[ 7. Cara output ini digunakan oleh project AboutCode lainnya untuk analisis lebih lanjut ]
- Sasaran: Bagian ini akan memberikan ringkasan dasar tentang cara hasil pemindaian scancode-toolkit dapat digunakan dalam berbagai penyebab, dan alat Aboutcode yang menyediakan fungsi tersebut.
- Ikhtisar Dasar:
- Scancode-Workbench Bagian ini menjelaskan visualisasi hasil dengan aplikasi desktop dan pointer ke dokumentasi scancode-workbench untuk mendapatkan dukungan lebih lanjut. Akan menambahkan dokumentasi yang diperlukan ke scancode-workbench jika diperlukan.
- Deltacode Cara hasil scancode 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 Command Line Scancode-Toolkit -> 2. Mulai Struktur Pembuatan Versi], masalah pembuatan versi opsi Command Line disebutkan. Hal yang sama juga diperlukan untuk bagian dokumentasi lainnya yang berisi perintah/informasi khusus versi yang akan menimbulkan kebingungan.
[ 2. Menetapkan Standar dan Pengujian Dokumentasi ]
Dokumentasi ini sudah memiliki pengujian untuk spinx-build (membangun semua halaman dan memeriksa apakah ada error sintaksis Sphinx) 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) Sekarang, linting memerlukan lebih banyak pemeriksaan untuk linting tertentu dalam reStructured Text dan standar lainnya. Hal ini dapat dicapai dengan restructuredtext-lint, tetapi memerlukan lebih banyak riset dan akan dilakukan sebagai bagian dari project GSoD saya.
[ 3. Menambahkan Bagian “Memulai” ]
Bagian ini akan berfungsi 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, termasuk Scancode-Toolkit, Scancode-Workbench, Deltacode, dan lainnya.
[ 4. Menyusun Ulang Menurut 4 Fungsi Dokumen ]
Dokumentasi yang ada tidak terstruktur secara eksplisit dalam 4 fungsi dokumen - Tutorial, Cara, Referensi, dan Penjelasan. Saya mengusulkan untuk menyusunnya dengan sesuai, menambahkan lebih banyak informasi/penjelasan/petunjuk jika diperlukan. Hal ini berlaku untuk semua project AboutCode dan dokumentasinya. Berikut adalah dua contoh penyusunan ulang dokumentasi Scancode-Toolkit yang saya usulkan dan ingin saya lanjutkan dalam project ini. Perubahan serupa akan diterapkan pada dokumentasi lainnya.
[ 5. Melakukan Restrukturisasi Halaman Pengembangan (Scancode-Toolkit) ]
Info selengkapnya tentang Kode/API dapat ditambahkan untuk membuatnya lebih cocok untuk developer. Dapat ada link ke [ 2. Diskusi yang menjelaskan bagian Pemindaian Kode di atas. Link ini akan menautkan penjelasan tentang cara kerja pemindaian dengan kode yang digunakannya untuk melakukan pemindaian. Seperti folder ini berisi bagian-bagian berbeda dari pemindai-toolkit, penggunaannya masing-masing dapat diuraikan dengan API, bersama dengan Diskusi tentang cara kerja pemindaian kode.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode : mengekstrak berbagai format arsip ]
- [ formattedcode : output formatting for different output file formats ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [ plugincode : class untuk arsitektur plugin ]
- [ summarycode : merangkum pemindaian pada lisensi yang terdeteksi ]
- [ textcode : handles text parsing ]
- [ typecode : menangani penentuan jenis file ]
- [ scancode : CLI dan API untuk scancode, bagian inti ]
Subbagian ini akan berisi informasi/API mendetail tentang bagian-bagian scancode-toolkit ini dalam subbagian yang sesuai. Panduan Pengembangan akan ada di halaman lain atau bagian lain yang memiliki subbagian yang lebih kecil.
[ 6. Menyusun ulang halaman FAQ (Scancode-Toolkit) ]
Halaman FAQ saat ini memiliki pertanyaan yang dapat dijawab dengan lebih baik dan harus disusun sebagai dokumen Cara, Tutorial, dan Referensi terpisah.
- Bagaimana cara kerja ScanCode? Masalah ini dirujuk dalam [ 2. Diskusi yang menjelaskan Pemindaian Kode ] dan akan menjadi bagian yang sepenuhnya terpisah dengan detail yang jauh lebih mendetail.
- How to Add New License Rules for Enhanced Detection? Masalah ini telah dibahas sebelumnya di Meningkatkan Cara yang ada, dokumentasi akan dipindahkan ke sana.
- Bagaimana cara menambahkan aturan deteksi lisensi baru? Hal ini dapat dibuat menjadi postingan “Cara” lain secara terpisah dan dapat diperluas.
- Bagaimana cara memulai Pengembangan? Sudah ada halaman pengembangan terpisah dan informasinya cukup tumpang-tindih. Restrukturisasi halaman pengembangan telah dibahas di atas.
- Langkah-langkah untuk memotong rilis baru Hal 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 “Cara”/”Tutorial”.