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