โครงสร้างเอกสารประกอบ NextPDF

โดยสรุป

คู่มือ NextPDF ปฏิบัติตามสัญญาโครงสร้างที่กำหนดไว้ตายตัว แต่ละหน้ามีหนึ่งหัวข้อ หนึ่งโหมด Diataxis และหนึ่งชนิดของหน้า ชนิดของหน้าแต่ละชนิดมีชุดหัวข้อระดับ 2 ที่ต้องมี manifest และเกตจำนวนไม่มากช่วยรักษาโครงสร้างให้คงเส้นคงวาเมื่อคู่มือขยายตัว

หน้านี้สรุปภาพรวมของระบบดังกล่าว เพื่อให้คุณกำหนดตำแหน่งของงานที่คุณมีส่วนร่วมได้อย่างถูกต้อง สัญญาเชิงบรรทัดฐานฉบับเต็ม ซึ่งรวมถึงรายการหัวข้อที่แน่นอน กฎการอ้างอิง และขั้นตอนการเชื่อมต่อเกต อยู่ในเอกสารกำกับดูแลภายใน docs/style/expansion-standard.md อ่านหน้านี้ก่อน แล้วเปิดเอกสารดังกล่าวประกอบเมื่อคุณเขียน

การเลือกชนิดของหน้า

ใช้กฎเหล่านี้ตามลำดับเพื่อตัดสินใจว่าจะเพิ่มหน้าใหม่หรือขยายหน้าที่มีอยู่:

1. หากเนื้อหาเป็นหัวข้อที่แยกต่างหาก ซึ่งผู้อ่านไม่คาดว่าจะพบในหน้าที่มีอยู่ ให้เพิ่มหน้าใหม่
2. หากเนื้อหาทำให้หัวข้อที่หน้าที่มีอยู่รับผิดชอบอยู่แล้วครบถ้วนขึ้น ให้ขยายหน้านั้น
3. หากเนื้อหาเป็นรายละเอียดเชิงลึกที่จะทำให้หน้าการติดตั้ง หน้าเริ่มต้นใช้งานอย่างรวดเร็ว หรือหน้างานยาวเกินไป ให้ย้ายไปยังหน้าแยกต่างหากและลิงก์ไปยังหน้านั้น
4. มิฉะนั้น ให้ขยายหน้าที่มีอยู่

หลังจากทราบแล้วว่าหน้านั้นควรมีอยู่ ให้กำหนดโหมด Diataxis ของหน้า โหมดจะกำหนดชนิดของหน้า:

• บทช่วยสอนมีไว้สอนผู้เรียน ใช้คู่มืองานที่เขียนเป็นสูตรขั้นตอน
• วิธีทำช่วยให้ผู้อ่านที่มีทักษะทำงานให้เสร็จ ใช้คู่มืองาน คู่มือ API ของเซิร์ฟเวอร์ หรือคู่มือชุดพัฒนาซอฟต์แวร์
• เอกสารอ้างอิงระบุข้อเท็จจริงที่เจาะจง ใช้เอกสารอ้างอิง API หรือหน้าดัชนี
• คำอธิบายสร้างความเข้าใจ ใช้คู่มือนักพัฒนาหรือคู่มือฟีเจอร์ระดับพรีเมียม

ภาษาที่เข้าใจง่ายเป็นเกณฑ์พื้นฐานสำหรับทุกโหมด ไม่ใช่โหมดแยกต่างหาก

แคตตาล็อกชนิดของหน้า

สัญญาของคู่มือรองรับชนิดเหล่านี้ ให้นำชนิดที่มีอยู่กลับมาใช้ซ้ำเสมอเมื่อหน้าของคุณมีตาราง API และเพิ่มชนิดแบบป้ายกำกับอย่างเดียวชนิดใหม่เฉพาะสำหรับหน้าที่ไม่มีตาราง API เท่านั้น

• ชนิดดัชนี: section-index, api-index, extension-index
• ชนิดอ้างอิง: api-reference ให้นำชนิดนี้กลับมาใช้ซ้ำสำหรับทุกหน้าที่มีตาราง API มาตรฐาน รวมถึงเอกสารอ้างอิงของเซิร์ฟเวอร์และ Python SDK
• ชนิดคำอธิบาย: developer-guide ให้นำชนิดนี้กลับมาใช้ซ้ำสำหรับเนื้อหาเกี่ยวกับสถาปัตยกรรม วงจรชีวิต และจุดต่อขยาย รวมถึงคู่มือของเซิร์ฟเวอร์และ Python SDK
• ชนิดแบบป้ายกำกับอย่างเดียวชนิดใหม่: premium-feature-guide และ task-guide ทั้งสองชนิดใช้สำหรับหน้าที่ไม่มีตาราง API

ทุกหน้าเริ่มต้นด้วย ## At a glance หน้า api-reference ทุกหน้ามีตาราง API ที่ใช้ร่วมกันและหัวข้อ Development notes หัวข้อที่กำหนดให้ต้องมีเป็นหัวข้อระดับ 2 โดยแต่ละหัวข้ออยู่บนบรรทัดของตนเอง คุณสามารถเพิ่มหัวข้ออื่นๆไว้ใต้หัวข้อเหล่านั้นได้

รายการตรวจสอบสำหรับการเขียน

เมื่อคุณเขียนหน้า ให้ทำตามรายการตรวจสอบทั้งสองรายการ มาตรฐานภายในระบุแต่ละรายการในเชิงบรรทัดฐาน และลิงก์ไปยังมาตรฐานที่รองรับรายการนั้น

ความเป็นมิตรต่อนักพัฒนา:

• ดึงตัวอย่างที่รันได้จาก examples/ หรือ tests/Cookbook และกำหนดสตริงข้อมูล title= ให้กับแต่ละบล็อกที่อยู่ในรั้วโค้ด
• ระบุข้อกำหนดเบื้องต้นใน front-matter และในส่วนเปิด
• แสดงผลลัพธ์ที่คาดหวังสำหรับตัวอย่างใดก็ตามที่มีผลลัพธ์ออกมา
• ทำให้บล็อกพร้อมสำหรับการคัดลอกและวาง: หนึ่งภาษาต่อหนึ่งบล็อก ใช้ชื่อเต็มเมื่อกล่าวถึงครั้งแรก และไม่มีอักขระพรอมต์ต่อท้าย
• แสดงโค้ดที่ปลอดภัยตามค่าเริ่มต้น: ตัวอย่างสำหรับใช้งานจริงใช้ try/catch กับข้อยกเว้น NextPDF ที่เฉพาะเจาะจงที่สุด และต้องไม่มี catch ที่ว่างเปล่า
• ปิดท้ายด้วยลิงก์สำหรับขั้นตอนถัดไปและกำหนด related: ใน front-matter

ความพร้อมสำหรับการแปล:

• เขียนหนึ่งแนวคิดต่อหนึ่งประโยคเพื่อให้การแปลด้วยเครื่องอยู่ในขอบเขต
• ทำให้หัวข้อและป้ายกำกับสั้น เพราะภาษาปลายทางส่วนใหญ่มีความยาวเพิ่มขึ้น
• หลีกเลี่ยงสำนวน
• คงชื่อสัญลักษณ์ คีย์การกำหนดค่า แฟล็ก CLI และชื่อข้อยกเว้นไว้ในรูปแบบโค้ด ส่วนชื่อมาตรฐานเช่น PDF/A-4, PAdES และ eIDAS จะไม่แปลเลย
• กำหนด i18n_ready และ xliff_segments ตามความจริง และเขียนในรูปแบบ Unicode NFC

สำหรับน้ำเสียง ตัวอย่างโค้ด คำศัพท์ และรูปแบบการอ้างอิง ให้ทำตามเอกสารทดแทนด้านรูปแบบที่ผ่านการรับรองซึ่งมาตรฐานภายในอ้างอิงถึง

การเชื่อมต่อกับเกต

เชื่อมต่อหน้าใหม่ตามลำดับขั้นตอนนี้:

1. สร้างโครงร่างของหน้าเพื่อให้ front-matter ตรงกับสคีมาของเว็บไซต์
2. เขียนเนื้อหาให้สอดคล้องกับหัวข้อที่ชนิดของหน้ากำหนดให้ต้องมี
3. เพิ่มรายการ { path, owner, kind, headings[] } ลงใน docs/manual-contract.json โดยเส้นทางสัมพัทธ์กับ src/content/docs ใช้เครื่องหมายทับไปข้างหน้า และต้องไม่มีเครื่องหมายทับนำหน้าหรือ ..
4. สำหรับเอกสารอ้างอิง API ให้เพิ่มสัญลักษณ์ของหน้าลงใน docs/api-coverage-manifest.json โดยสัญลักษณ์แต่ละรายการต้องปรากฏในหน้าและมีอยู่ในซอร์ส
5. อัปเดต docs/source-manifest.json เฉพาะเมื่อหน้านั้นมาจากที่เก็บซอร์สใหม่เท่านั้น
6. เพิ่มหน้าลงในกลุ่มแถบด้านข้างที่ถูกต้องใน astro.config.mjs ในรูปแบบรายการที่ระบุอย่างชัดเจน
7. เพิ่มแถวความครอบคลุมโลแคล โดยตั้งค่าเซลล์โลแคลทั้งสิบเจ็ดเซลล์เป็น missing สำหรับหน้าที่มีเฉพาะภาษาอังกฤษ
8. เรียกใช้เกตของเอกสารประกอบ การบิลด์ และงบประมาณด้านประสิทธิภาพ

หน้าที่เว็บไซต์เป็นเจ้าของอยู่ภายใต้ src/content/docs ตั้งค่า owner เป็น nextpdf-docs และต้องไม่มีเครื่องหมายการรวมข้อมูล หน้าที่รวมข้อมูลมาจากที่เก็บซอร์ส แฟล็กการเผยแพร่ของหน้าเหล่านั้นอยู่ใน front-matter ของซอร์ส ดังนั้นให้แก้ไขที่ซอร์สนั้น ไม่ใช่ที่นี่

ดูเพิ่มเติม

• Integrations: ตัวอย่างการใช้โครงสร้างคู่มือในงานจริงที่ใหญ่ที่สุด ซึ่งครอบคลุมแพ็กเกจจำนวนมาก
• เอกสารกำกับดูแลภายใน docs/style/expansion-standard.md มีสัญญาฉบับเต็ม: รายการหัวข้อที่แน่นอนสำหรับชนิดของหน้าทุกชนิด กฎการอ้างอิง และขั้นตอนการเชื่อมต่อเกตฉบับสมบูรณ์