Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan proyek
- Organisasi open source:
- AboutCode
- Penulis teknis:
- ayansinha
- Nama project:
- 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 tanda “--help” atau “-h”. Project ini bertujuan untuk membuat dokumentasi lengkap yang menjelaskan:
[ 1. Semua Opsi yang tersedia melalui Command Line ]
- Tujuan: Daftar lengkap semua opsi yang mungkin melalui command line.
- Ringkasan Dasar: Pertama, opsi pemindaian default dibahas, dengan contoh output. Grafik/deskripsi singkat tentang cara pemindaian dilakukan.
Selanjutnya, perilaku default ini akan berfungsi 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 berikutnya.
[ 2. Memulai Struktur Pembuatan Versi ]
- Tujuan: Memulai sistem pembuatan versi untuk mempertahankan opsi/API lintas rilis dan perubahan dokumentasi dengan benar.
- Masalah: Saat ini, dokumentasi di wiki dan halaman ReadTheDocs ditujukan untuk rilis yang lebih lama dan memerlukan penataan ulang yang signifikan.
- Ringkasan Dasar: Bagian scancode-toolkit yang telah diperbarui/dapat diperbarui dalam versi ini 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 diperbarui untuk setiap perubahan pada opsi dan dapat digunakan untuk mereplikasi pembuatan versi dalam dokumentasi.
[ 3. Cara menggunakan Opsi ini dalam berbagai kasus ]
- Tujuan: Bagian ini akan memberikan ringkasan dasar tentang cara penggunaan hasil pemindaian scancode-toolkit dalam berbagai kasus dan opsi Scancode-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 signifikan dari mentor dalam hal masukan tentang dan petunjuk ke berbagai kasus penggunaan Scancode-Toolkit.
[ 4. Perubahan yang dilakukan Opsi ini pada Pemindaian dan Output ]
- Tujuan: Bagian ini akan memberikan ringkasan dasar tentang cara hasil pemindaian scancode-toolkit dapat digunakan dalam berbagai kasus, 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 dibawa oleh semua opsi ke skenario default ini.
[ 5. Format Output dan contohnya ]
- Tujuan: Bagian ini akan memberikan ringkasan dasar tentang cara hasil pemindaian scancode-toolkit dapat digunakan dalam berbagai kasus, dan alat Aboutcode yang menyediakan fungsi tersebut.
- Ringkasan Dasar: Scancode-Tool memiliki tanda untuk menentukan berbagai format output tempat hasil pemindaian akan dibuat. Berikut adalah -
Bagian ini akan - menjelaskan format output secara mendetail
- memberikan contoh format output
- memberikan link lain yang sesuai dengan format output dan penggunaannya
- cara hasil pemindaian disimpan dalam file output. Bagian ini juga ditautkan ke Cara berbagai format ini dibuat, yang akan dijelaskan di [ 2. Diskusi yang menjelaskan Pemindaian Kode ].
[ 6. Penggunaan Bisnis Format Output Scancode ]
- Tujuan: Menjelaskan Kasus Penggunaan Bisnis 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 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 ]
- Tujuan: Bagian ini akan memberikan ringkasan dasar tentang cara hasil pemindaian scancode-toolkit dapat digunakan dalam berbagai kasus, dan alat Aboutcode yang menyediakan fungsi tersebut.
- Ringkasan Dasar:
- Scancode-Workbench Bagian ini menjelaskan cara memvisualisasikan hasil dengan aplikasi desktop dan petunjuk ke dokumentasi scancode-workbench untuk mendapatkan dukungan lebih lanjut tentang hal yang sama. Akan menambahkan dokumentasi yang diperlukan ke scancode-workbench jika perlu.
- Deltacode Cara hasil scancode diambil oleh Deltacode untuk menentukan perbedaan tingkat file antara dua codebase.
[ 2. Mengatur ulang struktur Dokumentasi AboutCode ]
Bagian ini mencakup berbagai perubahan pada Dokumentasi Aboutcode
[ 1. Sistem pembuatan versi ]
Dalam [ 1. Opsi Command Line Scancode-Toolkit -> 2. Initiate Versioning Structure], masalah pemberian versi pada opsi Command Line disebutkan. Hal yang sama juga diperlukan untuk bagian dokumentasi lainnya yang berisi perintah/informasi khusus versi yang dapat menimbulkan kebingungan.
[ 2. Menetapkan Standar dan Pengujian Dokumentasi ]
Dokumentasi ini sudah memiliki pengujian untuk spinx-build (membangun semua halaman dan memeriksa kesalahan sintaksis Sphinx di seluruhnya) 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, perlu 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 “Mulai” ]
Bagian ini akan berfungsi sebagai bagian awal bagi pendatang baru dan akan berisi kompilasi dokumen paling dasar dan penting untuk mulai menggunakan Project Aboutcode. Setiap Project Aboutcode akan memiliki bagian ini, termasuk Scancode-Toolkit, Scancode-Workbench, Deltacode, dan lainnya.
[ 4. Menyusun Ulang Sesuai dengan 4 Fungsi Dokumen ]
Dokumentasi yang ada tidak disusun secara eksplisit dalam 4 fungsi dokumen - Tutorial, Cara Melakukan, Referensi, dan Penjelasan. Saya mengusulkan untuk menyusunnya dengan tepat, menambahkan informasi/penjelasan/petunjuk apa pun yang diperlukan. Hal ini berlaku untuk semua project AboutCode dan dokumentasinya. Di bawah ini adalah dua contoh penataan ulang dokumentasi Scancode-Toolkit yang saya usulkan dan ingin saya lakukan dalam project ini. Perubahan serupa akan dilakukan pada dokumentasi lainnya.
[ 5. Menyusun Ulang Halaman Pengembangan (Scancode-Toolkit) ]
Info selengkapnya 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. Hal ini menghubungkan penjelasan tentang cara kerja pemindaian dengan kode yang digunakan untuk melakukan pemindaian. Seperti folder ini berisi berbagai bagian scancode-toolkit, penggunaan masing-masing dapat dijelaskan dengan API, bersama dengan Pembahasan tentang cara kerja scancode.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode : mengekstrak format arsip yang berbeda ]
- [ formattedcode : output formatting for different output file formats ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing berbagai format paket ]
- [ plugincode : class untuk arsitektur plugin ]
- [ summarycode : summarizes scan on detected licenses ]
- [ 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 scancode-toolkit ini dalam sub-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 terpisah yang berisi Cara Melakukan, Tutorial, dan Referensi.
- Bagaimana cara kerja ScanCode? Masalah ini dirujuk dalam [ 2. Diskusi yang menjelaskan Pemindaian Kode ] dan akan menjadi bagian yang sepenuhnya terpisah dengan detail yang lebih banyak.
- Bagaimana Cara Menambahkan Aturan Lisensi Baru untuk Deteksi yang Lebih Baik? Masalah ini sudah dibahas sebelumnya di Meningkatkan Kualitas Panduan 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 diuraikan lebih lanjut.
- Bagaimana cara memulai Pengembangan? Sudah ada halaman pengembangan terpisah dan informasinya cukup tumpang-tindih. Penataan ulang halaman pengembangan telah dibahas di atas.
- Langkah-langkah untuk merilis versi baru Bagian ini dapat diubah menjadi “Cara Merilis Versi Baru” yang terpisah.
- Temukan pertanyaan umum lainnya yang menjawab pertanyaan umum tentang project dan tidak termasuk dalam kategori “Cara Melakukan”/”Tutorial”.