หน้านี้มีรายละเอียดของโครงการเขียนเชิงเทคนิคที่ยอมรับใน Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- AboutCode
- ผู้เขียนด้านเทคนิค:
- อายานซินยา
- ชื่อโปรเจ็กต์:
- ข้อมูลอ้างอิงเกี่ยวกับ Command Line Options ใน scancode- Toolkit และจัดระเบียบโครงสร้างของเอกสาร AboutCode ที่ aboutcode.readthedocs.io
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
[ 1. ตัวเลือกบรรทัดคำสั่ง Scancode-Toolkit ]
Scancode-Toolkit มีโฮสต์ของตัวเลือกบรรทัดคำสั่งสำหรับปรับแต่งวิธีการสแกน รูปแบบเอาต์พุต และตัวเลือกอื่นๆ อีกมากมาย เช่น ปลั๊กอินหลังการสแกน ขณะนี้ตัวเลือกเหล่านี้ไม่มีเอกสารประกอบที่เหมาะสมเพื่ออธิบายและพร้อมใช้งานผ่านแฟล็ก "--help" หรือ "-h" เท่านั้น โปรเจ็กต์นี้มีจุดประสงค์เพื่อสร้างเอกสารประกอบฉบับสมบูรณ์ซึ่งอธิบายข้อมูลต่อไปนี้
[ 1. ตัวเลือกทั้งหมดที่มีในบรรทัดคำสั่ง ]
- เป้าหมาย: รายการตัวเลือกที่เป็นไปได้ทั้งหมดผ่านทางบรรทัดคำสั่ง
- ภาพรวมพื้นฐาน: อันดับแรก เราจะพูดถึงตัวเลือกการสแกนเริ่มต้นพร้อมตัวอย่างเอาต์พุต กราฟิก/คำอธิบายสั้นๆ เกี่ยวกับวิธีการสแกน
หลังจากนั้น ลักษณะการทำงานเริ่มต้นนี้จะทำหน้าที่เป็นข้อมูลอ้างอิงว่าตัวเลือกอื่นๆ เปลี่ยนแปลงการสแกนและเอาต์พุตอย่างไร
เราจะพูดถึงเรื่องนี้อย่างละเอียดและจะมีข้อมูลต่อไปนี้ตามที่ระบุไว้ในส่วนถัดไป
[ 2. เริ่มโครงสร้างการกำหนดเวอร์ชัน ]
- เป้าหมาย: เริ่มใช้ระบบการกำหนดเวอร์ชันเพื่อรักษาตัวเลือก/API และเอกสารต่างๆ ในรุ่นข้ามรุ่นให้เหมาะสม
- ปัญหา: ในขณะนี้ เอกสารประกอบใน Wiki และหน้า ReadTheDocs เป็นเอกสารสำหรับรุ่นเก่าและจำเป็นต้องมีการปรับโครงสร้างอย่างมาก
- ภาพรวมพื้นฐาน: ส่วนต่างๆ ของชุดเครื่องมือสแกนโค้ดที่ได้รับการอัปเดต/สามารถอัปเดตในเวอร์ชันได้มีดังนี้
- ตัวเลือกบรรทัดคำสั่ง
- API
- เอกสารประกอบ (ต้องเริ่มดำเนินการ) ตัวเลือกบรรทัดคำสั่งและ API มีการเปลี่ยนแปลงในเวอร์ชันและรุ่น อีกทั้งเอกสารก็ต้องดำเนินการตามมาด้วย มิเช่นนั้น ผู้ใช้อาจสับสนอย่างมาก ยูทิลิตีบรรทัดคำสั่ง [ --help ] มีการอัปเดตอยู่แล้วสำหรับการเปลี่ยนแปลงตัวเลือก และสามารถใช้เพื่อจำลองการกำหนดเวอร์ชันในเอกสาร
[ 3. ตัวเลือกเหล่านี้สามารถใช้ในกรณีต่างๆ ได้อย่างไร ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีการใช้งานผลการสแกนของชุดเครื่องมือสแกนในสาเหตุต่างๆ รวมถึงตัวเลือก Scancode-Toolkit ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมพื้นฐาน: ส่วนนี้จะแสดงตัวอย่างสถานการณ์การใช้งานที่แตกต่างกันและตัวเลือกที่แนะนำในสถานการณ์เหล่านั้น
- หมายเหตุ: ส่วนนี้ต้องอาศัยความช่วยเหลืออย่างมากจาก Mentor ในแง่ของการให้ข้อมูลและตัวชี้ไปยังกรณีการใช้งานต่างๆ ของ Scancode-Toolkit
[ 4. ตัวเลือกเหล่านี้มีการเปลี่ยนแปลงในการสแกนและ เอาต์พุต ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีการใช้งานผลการสแกนของชุดเครื่องมือสแกนในสาเหตุต่างๆ และเครื่องมือ Aboutcode ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมพื้นฐาน: ตัวเลือกนี้จะเปลี่ยนลักษณะการทำงานของการสแกน ตัวพิมพ์เริ่มต้นแบบพื้นฐานจะแสดงในส่วนนำหน้า [ 1 ตัวเลือกทั้งหมดที่มีให้ผ่านทาง Command Line ] และส่วนนี้จะเปรียบเทียบการเปลี่ยนแปลงที่ตัวเลือกทั้งหมดนำมาซึ่งสถานการณ์เริ่มต้นนี้
[ 5. รูปแบบเอาต์พุตและตัวอย่าง ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีการใช้งานผลการสแกนของชุดเครื่องมือสแกนในสาเหตุต่างๆ และเครื่องมือ Aboutcode ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมพื้นฐาน: เครื่องมือสแกนโค้ดมีแฟล็กเพื่อระบุรูปแบบเอาต์พุตต่างๆ ที่จะสร้างผลการสแกน ซึ่งได้แก่
ส่วนนี้จะ - อธิบายรูปแบบเอาต์พุตอย่างละเอียด
- แสดงตัวอย่างรูปแบบเอาต์พุต
- ให้ลิงก์อื่นๆ ที่เกี่ยวข้องกับรูปแบบเอาต์พุตและการใช้งาน
- วิธีจัดเก็บผลการสแกนในไฟล์เอาต์พุต นอกจากนี้ยังลิงก์ไปยังวิธีสร้างรูปแบบต่างๆ เหล่านี้ ซึ่งจะอธิบายไว้ใน [ 2 การสนทนาอธิบายการสแกนโค้ด ]
[ 6. การใช้รูปแบบเอาต์พุตของ Scancode สำหรับธุรกิจ ]
- เป้าหมาย: อธิบายกรณีการใช้งานทางธุรกิจของรูปแบบเอาต์พุต Scancode ในรายการแนวคิด GSoD รูปแบบเอาต์พุต Scancode กล่าวถึงเป็นแนวคิดการอ้างอิง ส่วนนี้ก็ใช้แนวทางเดียวกัน
- หมายเหตุ: ส่วนนี้ต้องการความช่วยเหลืออย่างมากจาก Mentor ในแง่ของการให้ข้อมูลและตัวชี้ไปยังกรณีการใช้งานต่างๆ ของธุรกิจของ Scancode-Toolkit
[ 7. โครงการ AboutCode นำเอาต์พุตเหล่านี้ไปใช้ในการวิเคราะห์เพิ่มเติมอย่างไร ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีการใช้งานผลการสแกนของชุดเครื่องมือสแกนในสาเหตุต่างๆ และเครื่องมือ Aboutcode ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมพื้นฐาน
- Scancode-Workbench ส่วนนี้จะอธิบายถึงการแสดงผลผลลัพธ์ด้วยแอปบนเดสก์ท็อป และตัวชี้ในเอกสารประกอบเกี่ยวกับ scancode-workbench จะเพิ่มเอกสารประกอบที่จำเป็นลงใน scancode-workbench หากจำเป็น
- Deltacode วิธีที่ Deltacode แสดงผลการสแกนโค้ดเพื่อระบุความแตกต่างของระดับไฟล์ระหว่างฐานของโค้ด 2 ฐาน
[ 2. จัดระเบียบโครงสร้างเอกสาร AboutCode ใหม่
ส่วนนี้รวมถึงโฮสต์ของการเปลี่ยนแปลงเอกสารประกอบของ Aboutcode
[ 1. ระบบการกำหนดเวอร์ชัน ]
ใน [ 1 ตัวเลือกบรรทัดคำสั่ง Scancode-Toolkit -> 2. เริ่มต้นโครงสร้างการกำหนดเวอร์ชัน] กล่าวถึงปัญหาเกี่ยวกับการกำหนดเวอร์ชันของตัวเลือกบรรทัดคำสั่ง กระบวนการดังกล่าวก็จำเป็นสำหรับส่วนอื่นๆ ของเอกสาร ซึ่งจะมีคำสั่ง/ข้อมูลเฉพาะเวอร์ชันที่อาจสร้างความสับสน
[ 2. การกำหนดมาตรฐานและการทดสอบเอกสารประกอบ ]
เอกสารประกอบมีการทดสอบสำหรับ Spinx-build (สร้างหน้าเว็บทั้งหมดและตรวจหาข้อผิดพลาดทางไวยากรณ์ของ Sphinx ทั้งหมด) และการตรวจสอบลิงก์ (ตรวจสอบลิงก์ทั้งหมดไปยังหน้าเว็บอื่นๆ จากเอกสารประกอบ) ด้วยการรวมอย่างต่อเนื่องผ่าน Travis-CI (ฉันเพิ่มไว้ในคำขอพุลนี้ #17 ) ตอนนี้เครื่องมือดังกล่าวต้องมีการตรวจสอบมากกว่านี้สำหรับการวิเคราะห์ข้อมูลที่เฉพาะเจาะจงในข้อความที่มีโครงสร้างใหม่และมาตรฐานอื่นๆ ซึ่งทำได้ด้วยการปรับโครงสร้างข้อความ แต่ต้องอาศัยการวิจัยเพิ่มเติมและจะทำโดยเป็นส่วนหนึ่งของโปรเจ็กต์ GSoD
[ 3. การเพิ่มส่วน "เริ่มต้นใช้งาน" ]
ส่วนนี้จะเป็นส่วนเริ่มต้นสำหรับผู้มาใหม่ และจะมีการรวบรวมเอกสารพื้นฐานและสำคัญที่สุดเพื่อเริ่มต้นใช้งาน Aboutcode Projects ทุกโปรเจ็กต์ Aboutcode จะมีส่วนนี้ รวมถึง Scancode-Toolkit, Scancode-Workbench, Deltacode และอื่นๆ
[ 4. ปรับโครงสร้างตามฟังก์ชันเอกสาร 4 ฟังก์ชัน ]
เอกสารประกอบที่มีอยู่ไม่ได้มีโครงสร้างที่ชัดเจนในฟังก์ชันเอกสาร 4 ฟังก์ชัน ซึ่งได้แก่ บทแนะนำ วิธีการ การอ้างอิง และคำอธิบาย ผมจึงเสนอที่จะจัดโครงสร้างสิ่งเหล่านี้ให้สอดคล้องกัน โดยเพิ่มข้อมูล/คำอธิบาย/ตัวชี้จากจุดที่จำเป็นเพิ่มเติม การระงับนี้สำหรับโปรเจ็กต์ AboutCode ทั้งหมดและเอกสารของโครงการ ด้านล่างนี้คือ 2 ตัวอย่างเอกสาร Scancode-Toolkit สำหรับการปรับโครงสร้างที่ฉันเสนอและต้องการดำเนินต่อในโปรเจ็กต์นี้ การเปลี่ยนแปลงที่คล้ายกันนี้จะดำเนินการในส่วนที่เหลือของเอกสารประกอบ
[ 5. การปรับโครงสร้างหน้าการพัฒนาใหม่ (Scancode-Toolkit) ]
สามารถเพิ่มข้อมูลเพิ่มเติมเกี่ยวกับโค้ด/API เพื่อช่วยให้นักพัฒนาซอฟต์แวร์ใช้งานได้ง่ายขึ้น อาจมีลิงก์ไปยัง [ 2 การสนทนาที่อธิบายเกี่ยวกับส่วน การสแกนโค้ด ] ด้านบน ซึ่งจะลิงก์คำอธิบายวิธีการทำงานของการสแกนกับโค้ดที่ใช้สแกน เช่นเดียวกับโฟลเดอร์เหล่านี้ที่ประกอบด้วยส่วนต่างๆ ของชุดเครื่องมือสแกนโค้ด การใช้งานของแต่ละรายการก็สามารถอธิบายอย่างละเอียดด้วย API ร่วมกับการพูดคุยเกี่ยวกับวิธีการทำงานของการสแกนโค้ดได้
- [ cluecode : ปลั๊กอินสำหรับสแกนใบอนุญาต ลิขสิทธิ์ URL อีเมล ]
- [ Commoncode : คลาสและฟังก์ชันตัวช่วย]
- [ แยกโค้ด : แตกไฟล์รูปแบบต่างๆ ]
- [ รหัสที่จัดรูปแบบ : การจัดรูปแบบเอาต์พุตสำหรับรูปแบบไฟล์เอาต์พุตต่างๆ ]
- [ Licensecode : รหัสตรวจจับใบอนุญาต ]
- [ packagedcode : การแยกวิเคราะห์แพ็กเกจรูปแบบต่างๆ ]
- [รหัสปลั๊กอิน : คลาสสำหรับสถาปัตยกรรมปลั๊กอิน ]
- [สรุปรหัส : สรุปการสแกนตามใบอนุญาตที่ตรวจพบ ]
- [ รหัสข้อความ : จัดการการแยกวิเคราะห์ข้อความ ]
- [ typecode : จัดการการกำหนดประเภทไฟล์ ]
- [ สแกนโค้ด : CLI และ API สำหรับสแกนโค้ด ส่วนหลัก ]
ส่วนย่อยนี้จะมีข้อมูลโดยละเอียด/API เกี่ยวกับส่วนเหล่านี้ของ scancode- Toolkit ในส่วนย่อย หลักเกณฑ์การพัฒนาจะอยู่ที่หน้าเว็บอื่นหรือส่วนอื่นที่มีส่วนย่อยที่เล็กกว่า
[ 6. การปรับโครงสร้างหน้าคำถามที่พบบ่อย (Scancode-Toolkit) ]
หน้าคำถามที่พบบ่อยในตอนนี้มีคำถามที่น่าจะให้คำตอบได้ดีกว่า และควรจัดโครงสร้างเป็น "วิธีการ" "บทแนะนำ" และ "เอกสารอ้างอิง" ที่แยกจากกัน
- ScanCode ทำงานอย่างไร มีการอ้างอิงปัญหานี้ใน [ 2 การสนทนาที่อธิบายถึง การสแกนโค้ด ] และจะแยกส่วนต่างหากและจะมีรายละเอียดมากขึ้น
- วิธีเพิ่มกฎใบอนุญาตใหม่สำหรับการตรวจจับที่ปรับปรุงแล้ว ก่อนหน้านี้เราได้พูดถึงปัญหานี้ไปแล้วในส่วนการปรับปรุงวิธีการที่มีอยู่ แต่เอกสารต่างๆ จะย้ายไปด้วย
- วิธีเพิ่มกฎการตรวจจับใบอนุญาตใหม่ ซึ่งอาจนำมาสร้างเป็นโพสต์ "วิธีการ" อีกโพสต์หนึ่งแยกต่างหากและนำไปต่อยอดได้
- วิธีเริ่มต้นใช้งานการพัฒนา เนื่องจากมีหน้าการพัฒนาแยกต่างหากอยู่แล้วและข้อมูลก็ซ้อนทับกันมาก การปรับโครงสร้างของหน้าการพัฒนาได้มีการกล่าวถึงไปก่อนหน้านี้
- ขั้นตอนการตัดต่อผลงานใหม่ อาจเปลี่ยนรูปแบบเป็น "วิธีการตัดต่อผลงานใหม่" แยกต่างหากได้
- ดูคำถามอื่นๆ ที่พบบ่อยซึ่งจะตอบคำถามทั่วไปเกี่ยวกับโปรเจ็กต์และไม่จัดอยู่ในหมวดหมู่ "วิธีการ"/"บทแนะนำ"