หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- AboutCode
- นักเขียนเชิงเทคนิค
- ayansinha
- ชื่อโปรเจ็กต์:
- ข้อมูลอ้างอิงสำหรับตัวเลือกบรรทัดคำสั่งในชุดเครื่องมือ scancode และจัดระเบียบโครงสร้างของเอกสาร AboutCode ที่ aboutcode.readthedocs.io
- ความยาวของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
[ 1. ตัวเลือกบรรทัดคำสั่งของ Scancode-Toolkit ]
Scancode-Toolkit มีตัวเลือกบรรทัดคำสั่งมากมายสำหรับปรับแต่งวิธีดำเนินการสแกน รูปแบบเอาต์พุต และตัวเลือกอื่นๆ อีกมากมาย เช่น ปลั๊กอินหลังการสแกน ปัจจุบันตัวเลือกเหล่านี้ไม่มีเอกสารประกอบที่อธิบายอย่างเหมาะสม และจะใช้ได้ผ่าน Flag "--help" หรือ "-h" เท่านั้น โปรเจ็กต์นี้มีวัตถุประสงค์เพื่อจัดทำเอกสารประกอบที่สมบูรณ์ซึ่งอธิบายถึงสิ่งต่อไปนี้
[ 1. ตัวเลือกทั้งหมดที่ใช้ได้ผ่านบรรทัดคำสั่ง ]
- เป้าหมาย: รายการตัวเลือกทั้งหมดที่เป็นไปได้ผ่านบรรทัดคำสั่ง
- ภาพรวมพื้นฐาน: ขั้นแรกจะกล่าวถึงตัวเลือกการสแกนเริ่มต้นพร้อมตัวอย่างเอาต์พุต กราฟิก/คําอธิบายสั้นๆ เกี่ยวกับวิธีทําการสแกน
หลังจากนี้ ลักษณะการทำงานเริ่มต้นนี้จะใช้เป็นข้อมูลอ้างอิงสำหรับวิธีที่ตัวเลือกอื่นๆ เปลี่ยนการสแกนและเอาต์พุต
รายการเหล่านี้ควรมีการพูดคุยอย่างละเอียดและจะมีข้อมูลต่อไปนี้ตามที่ระบุไว้ในส่วนถัดไป
[ 2. เริ่มโครงสร้างการกำหนดเวอร์ชัน ]
- เป้าหมาย: เริ่มต้นระบบการระบุเวอร์ชันเพื่อดูแลรักษาตัวเลือก/API และการเปลี่ยนแปลงเอกสารประกอบข้ามรุ่นอย่างเหมาะสม
- ปัญหา: ปัจจุบันเอกสารประกอบใน wiki และหน้า ReadTheGoogle เอกสารเป็นเอกสารรุ่นเก่าและต้องมีการปรับโครงสร้างครั้งใหญ่
- ภาพรวมเบื้องต้น: ส่วนของชุดเครื่องมือสแกนโค้ดที่อัปเดต/อาจอัปเดตในเวอร์ชัน
- ตัวเลือกบรรทัดคำสั่ง
- API
- เอกสารประกอบ (จะเริ่มต้น) ตัวเลือกบรรทัดคำสั่งและ API มีการเปลี่ยนแปลงในเวอร์ชันและรุ่นต่างๆ และเอกสารประกอบก็ต้องเปลี่ยนแปลงตามด้วย ไม่เช่นนั้นผู้ใช้จะสับสนอย่างมาก ยูทิลิตีบรรทัดคำสั่ง [ --help ] ได้รับการอัปเดตสำหรับการเปลี่ยนแปลงตัวเลือกแล้ว และสามารถใช้เพื่อจำลองการแยกเวอร์ชันในเอกสารประกอบได้
[ 3. การใช้ตัวเลือกเหล่านี้ในกรณีต่างๆ ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีใช้ผลลัพธ์การสแกนของ Scancode-Toolkit ในสาเหตุต่างๆ และตัวเลือก Scancode-Toolkit ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมพื้นฐาน: ส่วนนี้จะแสดงตัวอย่างสถานการณ์กรณีการใช้งานต่างๆ และตัวเลือกที่แนะนําในสถานการณ์เหล่านั้น
- หมายเหตุ: ส่วนนี้ต้องการความช่วยเหลืออย่างมากจากที่ปรึกษาในแง่ของอินพุตและคำแนะนำเกี่ยวกับ Use Case ต่างๆ ของScancode-Toolkit
[ 4. สิ่งที่ตัวเลือกเหล่านี้เปลี่ยนแปลงในการสแกนเอาต์พุต ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีใช้ผลลัพธ์การสแกนของ scancode-toolkit ในสาเหตุต่างๆ และเครื่องมือ Aboutcode ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมขั้นพื้นฐาน: ตัวเลือกนี้จะเปลี่ยนลักษณะการทำงานของการสแกน กรณีเริ่มต้นพื้นฐานจะแสดงในส่วนหน้า [ 1. ตัวเลือกทั้งหมดที่ใช้ได้ผ่านบรรทัดคำสั่ง ] และส่วนนี้จะเปรียบเทียบการเปลี่ยนแปลงที่ตัวเลือกทั้งหมดนำมาสู่สถานการณ์เริ่มต้นนี้
[ 5. รูปแบบเอาต์พุตและตัวอย่าง ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีใช้ผลลัพธ์การสแกนของ scancode-toolkit ในสาเหตุต่างๆ และเครื่องมือ Aboutcode ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมพื้นฐาน: เครื่องมือสแกนได้แจ้งว่ามี Flag เพื่อระบุรูปแบบเอาต์พุตที่แตกต่างกันซึ่งจะสร้างผลลัพธ์การสแกน ซึ่งได้แก่ -
ส่วนนี้จะ - อธิบายรูปแบบเอาต์พุตโดยละเอียด
- แสดงตัวอย่างรูปแบบเอาต์พุต
- ให้ลิงก์อื่นๆ ที่สอดคล้องกับรูปแบบเอาต์พุตและการใช้งาน
- วิธีจัดเก็บผลการสแกนไว้ในไฟล์เอาต์พุต ลิงก์นี้ยังลิงก์ไปยังวิธีสร้างรูปแบบต่างๆ เหล่านี้ด้วย ซึ่งจะอธิบายไว้ใน [ 2. การพูดคุยที่อธิบายการสแกนโค้ด ]
[ 6. การใช้รูปแบบเอาต์พุตสแกนสโค้ดเพื่อธุรกิจ ]
- เป้าหมาย: อธิบายกรณีการใช้งานทางธุรกิจของรูปแบบเอาต์พุตสแกนสโค้ด ในรายการไอเดีย GSoD มีการกล่าวถึงรูปแบบเอาต์พุตสแกนสโค้ดเป็นไอเดียอ้างอิง ส่วนนี้มีการใช้งานเช่นเดียวกัน
- หมายเหตุ: ส่วนนี้ต้องใช้ความช่วยเหลืออย่างมากจากพี่เลี้ยงในด้านข้อมูลและคำแนะนำเกี่ยวกับกรณีการใช้งานทางธุรกิจต่างๆ ของ Scancode-Toolkit
[ 7. โปรเจ็กต์อื่นๆ ของ AboutCode ใช้เอาต์พุตเหล่านี้เพื่อการวิเคราะห์เพิ่มเติมอย่างไร ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีใช้ผลลัพธ์การสแกนของ scancode-toolkit ในสาเหตุต่างๆ และเครื่องมือ Aboutcode ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมพื้นฐาน
- Scancode-Workbench ส่วนนี้จะอธิบายการแสดงภาพผลลัพธ์ด้วยแอปบนเดสก์ท็อปและตัวชี้ไปยังเอกสาร scancode-workbench เพื่อรับการสนับสนุนเพิ่มเติม จะเพิ่มเอกสารประกอบที่จำเป็นลงใน scancode-workbench หากจำเป็น
- Deltacode Deltacode จะแสดงผลการสแกนโค้ดเพื่อระบุความแตกต่างของระดับไฟล์ระหว่างโค้ดเบส 2 แบบ
[ 2. จัดระเบียบโครงสร้างของเอกสารประกอบ AboutCode ใหม่ ]
ส่วนนี้รวมถึงโฮสต์การเปลี่ยนแปลงในเอกสาร Aboutcode
[ 1. ระบบการกำหนดเวอร์ชัน ]
ใน [ 1. ตัวเลือกบรรทัดคำสั่ง scancode-Toolkit -> 2. เริ่มโครงสร้างเวอร์ชัน] มีการพูดถึงปัญหาเกี่ยวกับเวอร์ชันของตัวเลือกบรรทัดคำสั่ง ในส่วนอื่นๆ ของเอกสารประกอบก็ควรทำเช่นเดียวกัน หากมีคำสั่ง/ข้อมูลเฉพาะเวอร์ชันที่อาจทำให้เกิดความสับสน
[ 2. การตั้งค่ามาตรฐานและการทดสอบของเอกสาร ]
เอกสารประกอบมีการทดสอบ Spinx-build (สร้างหน้าเว็บทั้งหมดและตรวจหาข้อผิดพลาดทางไวยากรณ์ของ Sphinx ทั่วทั้งเอกสาร) และการตรวจสอบลิงก์ (ตรวจสอบลิงก์ทั้งหมดที่ไปยังหน้าเว็บอื่นๆ จากเอกสารประกอบ) โดยใช้การรวมอย่างต่อเนื่องผ่าน Travis-CI (Added by me in this Pull Request #17 ) ตอนนี้ต้องการตรวจสอบเพิ่มเติมสำหรับการขัดเกลาเฉพาะใน reStructured Text และมาตรฐานอื่นๆ ซึ่งทำได้ด้วย restructuredtext-lint แต่ต้องค้นคว้าเพิ่มเติมและจะดำเนินการเป็นส่วนหนึ่งของโปรเจ็กต์ GSoD
[ 3. การเพิ่มส่วน "เริ่มต้นใช้งาน" ]
ซึ่งจะเป็นส่วนเริ่มต้นสำหรับมือใหม่ และจะประกอบด้วยเอกสารพื้นฐานและสำคัญที่สุดในการเริ่มต้นใช้งานโปรเจ็กต์ Aboutcode โปรเจ็กต์ Aboutcode ทุกโปรเจ็กต์จะมีส่วนนี้ รวมถึง Scancode-Toolkit, Scancode-Workbench, Deltacode และอื่นๆ
[ 4. การปรับโครงสร้างตามฟังก์ชันเอกสาร 4 รายการ ]
เอกสารประกอบที่มีอยู่ไม่ได้จัดโครงสร้างตามฟังก์ชันของเอกสาร 4 ประเภทอย่างชัดเจน ได้แก่ บทแนะนำ วิธีการ ข้อมูลอ้างอิง และคำอธิบาย ฉันเสนอที่จะจัดโครงสร้างตามนั้น โดยเพิ่มข้อมูล/คำอธิบาย/ชี้แนะตามความจำเป็น ข้อกำหนดนี้มีผลกับโปรเจ็กต์และเอกสารประกอบทั้งหมดของ AboutCode ด้านล่างนี้คือตัวอย่าง 2 ตัวอย่างของการปรับเปลี่ยนโครงสร้างเอกสารประกอบของ Scancode-Toolkit ที่ฉันเสนอและต้องการนำไปใช้ในโปรเจ็กต์นี้ เราจะทำการเปลี่ยนแปลงที่คล้ายกันในเอกสารประกอบที่เหลือ
[ 5. การปรับโครงสร้างหน้าการพัฒนา (Scancode-Toolkit) ]
คุณสามารถเพิ่มข้อมูลเพิ่มเติมเกี่ยวกับโค้ด/API เพื่อให้นักพัฒนาแอปใช้งานได้ง่ายขึ้น อาจมีลิงก์ไปยัง [ 2. การพูดคุยที่อธิบายส่วนการสแกนโค้ด ] ด้านบน ซึ่งจะลิงก์คําอธิบายวิธีการทํางานของการสแกนกับโค้ดที่ใช้สําหรับสแกน เช่นเดียวกับโฟลเดอร์เหล่านี้ที่มีส่วนต่างๆ ของชุดเครื่องมือสแกนสโค้ด การใช้งานแต่ละรายการสามารถอธิบายเพิ่มเติมได้ด้วย API ร่วมกับการสนทนาเกี่ยวกับวิธีการทํางานของสแกนสโค้ด
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode : extracts different archive formats ]
- [ formattedcode : output formatting for different output file formats ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [ plugincode : classes for the plugins architecture ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : handles text parsing ]
- [ typecode : handles file type determinations ]
- [ scancode : CLI and API to scancode, the core part ]
ส่วนย่อยนี้จะมีข้อมูล/API โดยละเอียดเกี่ยวกับส่วนต่างๆ ของชุดเครื่องมือสแกนโยกในหัวข้อย่อยตามลำดับ หลักเกณฑ์การพัฒนาจะอยู่ในหน้าอื่นหรือส่วนอื่นที่มีส่วนย่อยที่เล็กกว่า
[ 6. การปรับโครงสร้างหน้าคำถามที่พบบ่อย (Scancode-Toolkit) ]
ปัจจุบันหน้าคำถามที่พบบ่อยมีคำถามที่ตอบได้ดีกว่าและควรมีโครงสร้างเป็นเอกสารวิธีการ บทแนะนำ และเอกสารอ้างอิงแยกต่างหาก
- ScanCode ทำงานอย่างไร ปัญหานี้มีการอ้างอิงใน [ 2. การสนทนาอธิบายถึง การสแกนโค้ด ] และจะเป็นส่วนแยกต่างหากทั้งหมดโดยมีรายละเอียดเพิ่มเติม
- วิธีเพิ่มกฎใบอนุญาตใหม่สำหรับการเพิ่มประสิทธิภาพการตรวจจับ เราได้พูดถึงปัญหานี้ไปแล้วในขั้นตอนการปรับปรุงวิธีการที่มีอยู่แล้ว เอกสารจะย้ายมาไว้ที่ส่วนนี้
- วิธีเพิ่มกฎการตรวจหาใบอนุญาตใหม่ เรื่องนี้อาจทำเป็นโพสต์ "วิธีการ" แยกต่างหากและขยายความได้
- วิธีเริ่มต้นการพัฒนา มีหน้าการพัฒนาแยกต่างหากอยู่แล้วและข้อมูลทับซ้อนกันมาก เราได้พูดคุยเกี่ยวกับการปรับโครงสร้างหน้าการพัฒนาไปแล้วข้างต้น
- ขั้นตอนในการตัดรุ่นใหม่ เปลี่ยนเป็น "วิธีตัดรุ่นใหม่" แยกต่างหากได้
- ดูคำถามที่พบบ่อยเพิ่มเติมซึ่งตอบคำถามทั่วไปเกี่ยวกับโครงการและไม่อยู่ในหมวดหมู่ "วิธีการ"/"บทแนะนำ"