หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- AboutCode
- นักเขียนเชิงเทคนิค:
- ayansinha
- ชื่อโปรเจ็กต์:
- Reference for Command Line Options in scancode-toolkit and Reorganize the structure of AboutCode documentation at aboutcode.readthedocs.io
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
[ 1. ตัวเลือกบรรทัดคำสั่งของ Scancode-Toolkit ]
Scancode-Toolkit มีตัวเลือกบรรทัดคำสั่งมากมายเพื่อปรับแต่งวิธีดำเนินการสแกน รูปแบบเอาต์พุต และตัวเลือกอื่นๆ อีกหลายอย่าง เช่น ปลั๊กอินหลังการสแกน ปัจจุบันตัวเลือกเหล่านี้ไม่มีเอกสารประกอบที่เหมาะสมเพื่ออธิบาย และใช้ได้ผ่านแฟล็ก "--help" หรือ "-h" เท่านั้น โปรเจ็กต์นี้มีเป้าหมายเพื่อสร้างเอกสารประกอบที่สมบูรณ์ซึ่งอธิบายสิ่งต่อไปนี้
[ 1. ตัวเลือกทั้งหมดที่ใช้ได้ผ่านบรรทัดคำสั่ง ]
- เป้าหมาย: รายการตัวเลือกทั้งหมดที่เป็นไปได้ผ่านบรรทัดคำสั่ง
- ภาพรวมเบื้องต้น: ขั้นแรก เราจะพูดถึงตัวเลือกการสแกนเริ่มต้นพร้อมตัวอย่างเอาต์พุต กราฟิก/คำอธิบายสั้นๆ เกี่ยวกับวิธีดำเนินการสแกน
จากนี้ไป ลักษณะการทำงานเริ่มต้นนี้จะใช้เป็นข้อมูลอ้างอิงเพื่ออธิบายว่าตัวเลือกอื่นๆ เปลี่ยนการสแกนและเอาต์พุตอย่างไร
เราจะพูดถึงตัวเลือกเหล่านี้โดยละเอียดและจะรวมข้อมูลต่อไปนี้ตามที่ระบุไว้ในส่วนถัดไป
[ 2. เริ่มต้นโครงสร้างการกำหนดเวอร์ชัน ]
- เป้าหมาย: เริ่มระบบการกำหนดเวอร์ชันเพื่อดูแลตัวเลือก/API และการเปลี่ยนแปลงเอกสารประกอบระหว่างรุ่นต่างๆ อย่างเหมาะสม
- ปัญหา: ปัจจุบันเอกสารประกอบในหน้า Wiki และ ReadTheDocs เป็นเอกสารประกอบสำหรับรุ่นเก่าและต้องมีการปรับโครงสร้างครั้งใหญ่
- ภาพรวมเบื้องต้น: ส่วนต่างๆ ของ Scancode-Toolkit ที่ได้รับการอัปเดต/อาจได้รับการอัปเดตในเวอร์ชันต่างๆ ได้แก่
- ตัวเลือกบรรทัดคำสั่ง
- API
- เอกสารประกอบ (ที่จะเริ่มต้น) ตัวเลือกบรรทัดคำสั่งและ API จะมีการเปลี่ยนแปลงในเวอร์ชันและการเผยแพร่ต่างๆ และเอกสารประกอบก็ต้องมีการเปลี่ยนแปลงตามด้วย ไม่เช่นนั้นจะทำให้ผู้ใช้สับสนอย่างมาก ยูทิลิตีบรรทัดคำสั่ง [ --help ] ได้รับการอัปเดตสำหรับการเปลี่ยนแปลงตัวเลือกต่างๆ แล้ว และสามารถใช้เพื่อจำลองการกำหนดเวอร์ชันในเอกสารประกอบได้
[ 3. วิธีใช้ตัวเลือกเหล่านี้ในกรณีต่างๆ ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีใช้ผลการสแกนของ Scancode-Toolkit ในกรณีต่างๆ และตัวเลือก Scancode-Toolkit ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมเบื้องต้น: ส่วนนี้จะแสดงตัวอย่างสถานการณ์การใช้งานต่างๆ และตัวเลือกที่แนะนำในสถานการณ์เหล่านั้น
- หมายเหตุ: ส่วนนี้ต้องได้รับความช่วยเหลืออย่างมากจากผู้ให้คำปรึกษาในแง่ของข้อมูลและคำแนะนำเกี่ยวกับกรณีการใช้งานต่างๆ ของ Scancode-Toolkit
[ 4. สิ่งที่ตัวเลือกเหล่านี้เปลี่ยนแปลงในการสแกนและเอาต์พุต ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีใช้ผลการสแกนของ Scancode-Toolkit ในกรณีต่างๆ และเครื่องมือ Aboutcode ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมเบื้องต้น: ตัวเลือกต่างๆ จะเปลี่ยนลักษณะการทำงานของวิธีดำเนินการสแกน เราจะแสดงกรณีเริ่มต้นพื้นฐานในส่วนนำ [ 1. ตัวเลือกทั้งหมดที่ใช้ได้ผ่านบรรทัดคำสั่ง ] และส่วนนี้จะเปรียบเทียบการเปลี่ยนแปลงที่ตัวเลือกทั้งหมดนำมาสู่สถานการณ์เริ่มต้นนี้
[ 5. รูปแบบเอาต์พุตและตัวอย่าง ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีใช้ผลการสแกนของ Scancode-Toolkit ในกรณีต่างๆ และเครื่องมือ Aboutcode ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมเบื้องต้น: Scancode-Tool มีแฟล็กสำหรับระบุรูปแบบเอาต์พุตต่างๆ ที่จะสร้างผลการสแกน ซึ่งได้แก่ -
ส่วนนี้จะ - อธิบายรูปแบบเอาต์พุตโดยละเอียด
- แสดงตัวอย่างรูปแบบเอาต์พุต
- แสดงลิงก์อื่นๆ ที่เกี่ยวข้องกับรูปแบบเอาต์พุตและการใช้งาน
- วิธีจัดเก็บผลการสแกนในไฟล์เอาต์พุต นอกจากนี้ ส่วนนี้ยังลิงก์ไปยังวิธีสร้างรูปแบบต่างๆ ซึ่งจะอธิบายไว้ใน [ 2. การอธิบายการสแกนโค้ด ]
[ 6. การใช้งานรูปแบบเอาต์พุตของ Scancode ในธุรกิจ ]
- เป้าหมาย: อธิบายกรณีการใช้งานรูปแบบเอาต์พุตของ Scancode ในธุรกิจ ในรายการไอเดีย GSoD มีการระบุรูปแบบเอาต์พุตของ Scancode เป็นไอเดียอ้างอิง ส่วนนี้จะนำไอเดียดังกล่าวไปใช้
- หมายเหตุ: ส่วนนี้ต้องได้รับความช่วยเหลืออย่างมากจากผู้ให้คำปรึกษาในแง่ของข้อมูลและคำแนะนำเกี่ยวกับกรณีการใช้งานต่างๆ ของ Scancode-Toolkit ในธุรกิจ
[ 7. วิธีที่โปรเจ็กต์ AboutCode อื่นๆ ใช้เอาต์พุตเหล่านี้เพื่อการวิเคราะห์เพิ่มเติม ]
- เป้าหมาย: ส่วนนี้จะให้ข้อมูลสรุปเบื้องต้นเกี่ยวกับวิธีใช้ผลการสแกนของ Scancode-Toolkit ในกรณีต่างๆ และเครื่องมือ Aboutcode ที่มีฟังก์ชันการทำงานดังกล่าว
- ภาพรวมเบื้องต้น:
- Scancode-Workbench ส่วนนี้จะอธิบายการแสดงภาพผลลัพธ์ด้วยแอปเดสก์ท็อปและคำแนะนำเกี่ยวกับเอกสารประกอบ Scancode-Workbench เพื่อขอรับความช่วยเหลือเพิ่มเติมเกี่ยวกับเรื่องนี้ และจะเพิ่มเอกสารประกอบที่จำเป็นลงใน Scancode-Workbench หากจำเป็น
- Deltacode วิธีที่ Deltacode ใช้ผลการสแกนของ Scancode เพื่อกำหนดความแตกต่างระดับไฟล์ระหว่างฐานโค้ด 2 ฐาน
[ 2. จัดระเบียบโครงสร้างเอกสารประกอบของ AboutCode ใหม่ ]
ส่วนนี้รวมถึงการเปลี่ยนแปลงมากมายในเอกสารประกอบของ Aboutcode
[ 1. ระบบการกำหนดเวอร์ชัน ]
ใน [ 1. ตัวเลือกบรรทัดคำสั่งของ Scancode-Toolkit -> 2. เริ่มต้นโครงสร้างการกำหนดเวอร์ชัน] เราได้พูดถึงปัญหาการกำหนดเวอร์ชันตัวเลือกบรรทัดคำสั่ง การกำหนดเวอร์ชันเป็นสิ่งจำเป็นสำหรับส่วนอื่นๆ ของเอกสารประกอบด้วย ซึ่งมีคำสั่ง/ข้อมูลเฉพาะเวอร์ชันที่อาจทำให้เกิดความสับสน
[ 2. การตั้งค่ามาตรฐานและทดสอบเอกสารประกอบ ]
เอกสารประกอบมีการทดสอบ spinx-build (สร้างหน้าทั้งหมดและตรวจสอบข้อผิดพลาดของไวยากรณ์ Sphinx ทั่วทั้งเอกสาร) และการตรวจสอบลิงก์ (ตรวจสอบลิงก์ทั้งหมดไปยังหน้าเว็บอื่นๆ จากเอกสารประกอบ) ด้วยการผสานรวมอย่างต่อเนื่องผ่าน Travis-CI อยู่แล้ว (ฉันเพิ่มการทดสอบเหล่านี้ในคำขอแบบดึง #17) ตอนนี้เอกสารประกอบต้องมีการตรวจสอบเพิ่มเติมสำหรับการ Linting ที่เฉพาะเจาะจงใน 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. การอธิบายการสแกนโค้ด ] ด้านบน ซึ่งจะลิงก์คำอธิบายเกี่ยวกับวิธีทำงานของการสแกนไปยังโค้ดที่ใช้ในการดำเนินการสแกน เช่น โฟลเดอร์เหล่านี้มีส่วนต่างๆ ของ Scancode-Toolkit เราสามารถอธิบายการใช้งานแต่ละส่วนได้ด้วย API ร่วมกับคำอธิบายเกี่ยวกับวิธีทำงานของ Scancode
- [ cluecode : ปลั๊กอินสำหรับการสแกนใบอนุญาต ลิขสิทธิ์ URL อีเมล ]
- [ commoncode : คลาสและฟังก์ชันตัวช่วย]
- [ extractcode : แยกรูปแบบไฟล์เก็บถาวรต่างๆ ]
- [ formattedcode : การจัดรูปแบบเอาต์พุตสำหรับรูปแบบไฟล์เอาต์พุตต่างๆ ]
- [ licensedcode : โค้ดการตรวจหาใบอนุญาต ]
- [ packagedcode : การแยกวิเคราะห์รูปแบบแพ็กเกจต่างๆ ]
- [ plugincode : คลาสสำหรับสถาปัตยกรรมปลั๊กอิน ]
- [ summarycode : สรุปการสแกนใบอนุญาตที่ตรวจพบ ]
- [ textcode : จัดการการแยกวิเคราะห์ข้อความ ]
- [ typecode : จัดการการกำหนดประเภทไฟล์ ]
- [ scancode : CLI และ API สำหรับ Scancode ซึ่งเป็นส่วนหลัก ]
ส่วนย่อยนี้จะมีข้อมูล/API โดยละเอียดเกี่ยวกับส่วนต่างๆ ของ Scancode-Toolkit ในส่วนย่อยย่อยตามลำดับ หลักเกณฑ์การพัฒนาจะอยู่ในหน้าอื่นหรือส่วนอื่นที่มีส่วนย่อยที่เล็กลง
[ 6. การปรับโครงสร้างหน้าคำถามที่พบบ่อย (Scancode-Toolkit) ใหม่
ปัจจุบันหน้าคำถามที่พบบ่อยมีคำถามที่สามารถตอบได้ดีขึ้นและควรจัดโครงสร้างเป็นเอกสารวิธีใช้ บทแนะนำ และเอกสารอ้างอิงแยกกัน
- ScanCode ทำงานอย่างไร เราได้อ้างอิงถึงคำถามนี้ใน [ 2. การอธิบายการสแกนโค้ด ] และจะอธิบายคำถามนี้ในส่วนแยกต่างหากโดยละเอียดมากขึ้น
- วิธีเพิ่มกฎใบอนุญาตใหม่เพื่อการตรวจหาที่ดียิ่งขึ้น เราได้พูดถึงคำถามนี้ก่อนหน้านี้แล้วในส่วนการปรับปรุงเอกสารวิธีใช้ที่มีอยู่ เราจะย้ายเอกสารประกอบไปที่ส่วนนั้น
- วิธีเพิ่มกฎการตรวจหาใบอนุญาตใหม่ เราสามารถสร้างคำถามนี้เป็นโพสต์ "วิธีใช้" อีกรายการแยกต่างหากและอธิบายรายละเอียดเพิ่มเติมได้
- วิธีเริ่มต้นใช้งานการพัฒนา เรามีหน้าการพัฒนาแยกต่างหากอยู่แล้วและข้อมูลในหน้าดังกล่าวซ้ำซ้อนกันค่อนข้างมาก เราได้พูดถึงการปรับโครงสร้างหน้าการพัฒนาใหม่แล้วข้างต้น
- ขั้นตอนในการเผยแพร่เวอร์ชันใหม่ เราสามารถเปลี่ยนคำถามนี้เป็น "วิธีเผยแพร่เวอร์ชันใหม่" แยกต่างหากได้
- ค้นหาคำถามที่พบบ่อยเพิ่มเติมซึ่งตอบคำถามทั่วไปเกี่ยวกับโปรเจ็กต์และไม่ได้อยู่ในหมวดหมู่ "วิธีใช้"/"บทแนะนำ"