วิธีการจัดทำเอกสารรหัส Python โดยใช้ Doxygen [ปิด]

ฉันชอบ Doxygen ในการสร้างเอกสารของรหัส C หรือ PHP ฉันมีโครงการ Python ที่กำลังจะมาถึงและฉันคิดว่าฉันจำได้ว่า Python ไม่มี/* .. */ความคิดเห็นและยังมีสิ่งอำนวยความสะดวกในการจัดทำเอกสารด้วยตนเองซึ่งดูเหมือนจะเป็นวิธีการจัดทำเอกสารแบบไพ ธ อน

เนื่องจากฉันคุ้นเคยกับ Doxygen ฉันจะใช้มันเพื่อสร้างเอกสาร Python ได้อย่างไร มีอะไรเป็นพิเศษที่ฉันต้องระวังหรือไม่?

สิ่งนี้บันทึกไว้ในเว็บไซต์ doxygenแต่สรุปได้ที่นี่:

คุณสามารถใช้ doxygen เพื่อจัดทำเอกสารรหัส Python ของคุณ คุณสามารถใช้ไวยากรณ์สตริงเอกสาร Python:

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

ในกรณีนี้ความคิดเห็นจะถูกดึงออกมาโดย doxygen แต่คุณจะไม่สามารถใช้คำสั่ง doxygen พิเศษใด ๆได้

หรือคุณสามารถ (คล้ายกับภาษาสไตล์ C ภายใต้ doxygen) เพิ่มเครื่องหมายแสดงความคิดเห็น ( #) ในบรรทัดแรกก่อนสมาชิก:

## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

ในกรณีนั้นคุณสามารถใช้คำสั่ง doxygen พิเศษ ไม่มีโหมดเอาต์พุต Python โดยเฉพาะ แต่คุณสามารถปรับปรุงผลลัพธ์ได้โดยตั้งค่าOPTMIZE_OUTPUT_JAVAเป็นYES.

จริงๆแล้วฉันรู้สึกประหลาดใจเล็กน้อยกับความแตกต่างดูเหมือนว่าครั้งหนึ่ง doxygen สามารถตรวจจับความคิดเห็นใน ## บล็อกหรือบล็อก "" "ได้งานส่วนใหญ่จะเสร็จสิ้นและคุณจะสามารถใช้คำสั่งพิเศษใน ทั้งสองกรณีบางทีพวกเขาอาจคาดหวังว่าผู้คนที่ใช้ "" "จะปฏิบัติตามแนวทางปฏิบัติเกี่ยวกับเอกสาร Pythonic มากขึ้นและจะรบกวนคำสั่ง doxygen พิเศษหรือไม่?

doxypyกรองขาเข้าช่วยให้คุณใช้สวยมากทุก Doxygen ของการจัดรูปแบบแท็กในรูปแบบมาตรฐาน docstring หลาม ฉันใช้มันเพื่อจัดทำเอกสารเฟรมเวิร์กแอปพลิเคชันเกม C ++ และ Python แบบผสมขนาดใหญ่และใช้งานได้ดี

ท้ายที่สุดคุณมีเพียงสองทางเลือก:

คุณสร้างเนื้อหาของคุณโดยใช้ Doxygen หรือคุณสร้างเนื้อหาของคุณโดยใช้ Sphinx *

1. Doxygen : ไม่ใช่เครื่องมือที่เลือกใช้สำหรับโครงการ Python ส่วนใหญ่ แต่ถ้าคุณต้องจัดการกับโปรเจ็กต์อื่น ๆ ที่เกี่ยวข้องซึ่งเขียนด้วยภาษา C หรือ C ++ มันก็สมเหตุสมผลดี สำหรับนี้คุณสามารถปรับปรุงการบูรณาการระหว่าง Doxygen และ Python ใช้doxypypy

2. Sphinx : เครื่องมือ defacto สำหรับจัดทำเอกสารโครงการ Python คุณมีสามตัวเลือกที่นี่: ด้วยตนเอง, กึ่งอัตโนมัติ (การสร้างต้นขั้ว) และอัตโนมัติเต็มรูปแบบ (Doxygen like)

   1. สำหรับเอกสาร API คู่มือคุณมีสฟิงซ์AutoDoc นี่เป็นวิธีที่ดีในการเขียนคู่มือผู้ใช้ที่มีองค์ประกอบที่สร้าง API ในตัว
   2. สำหรับกึ่งอัตโนมัติคุณมีสฟิงซ์autosummary คุณสามารถตั้งค่าระบบสร้างของคุณเพื่อเรียกใช้ sphinx-autogen หรือตั้งค่า Sphinx ของคุณด้วยการautosummary_generateกำหนดค่า คุณจะต้องตั้งค่าเพจด้วยการสรุปอัตโนมัติจากนั้นแก้ไขเพจด้วยตนเอง คุณมีตัวเลือก แต่ประสบการณ์ของฉันกับแนวทางนี้คือต้องใช้การกำหนดค่ามากเกินไปและในตอนท้ายแม้ว่าจะสร้างเทมเพลตใหม่แล้วฉันก็พบข้อบกพร่องและความเป็นไปไม่ได้ที่จะระบุได้ว่าสิ่งใดถูกเปิดเผยว่าเป็น API สาธารณะหรือไม่ ความคิดเห็นของฉันคือเครื่องมือนี้ดีสำหรับการสร้างต้นขั้วที่จะต้องมีการแก้ไขด้วยตนเองและไม่มีอะไรเพิ่มเติม เปรียบเสมือนทางลัดที่จะลงเอยด้วยตนเอง
   3. อัตโนมัติเต็มรูปแบบ สิ่งนี้ถูกวิพากษ์วิจารณ์หลายครั้งและเป็นเวลานานแล้วที่เราไม่มีตัวสร้าง Python API อัตโนมัติที่ดีที่รวมเข้ากับ Sphinx จนกระทั่งAutoAPIมาซึ่งเป็นเด็กใหม่ในบล็อก นี่เป็นวิธีที่ดีที่สุดสำหรับการสร้าง API อัตโนมัติใน Python (หมายเหตุ: การโปรโมตตัวเองแบบไร้ยางอาย)

มีตัวเลือกอื่น ๆ ที่ควรทราบ:

• Breathe : สิ่งนี้เริ่มต้นเป็นความคิดที่ดีมากและเหมาะสมเมื่อคุณทำงานกับโครงการที่เกี่ยวข้องหลายโครงการในภาษาอื่น ๆ ที่ใช้ Doxygen แนวคิดคือใช้เอาต์พุต Doxygen XML และป้อนให้กับ Sphinx เพื่อสร้าง API ของคุณ ดังนั้นคุณสามารถรักษาความดีทั้งหมดของ Doxygen และรวมระบบเอกสารใน Sphinx ยอดเยี่ยมในทางทฤษฎี ตอนนี้ในทางปฏิบัติครั้งสุดท้ายที่ฉันตรวจสอบโครงการยังไม่พร้อมสำหรับการผลิต
• pydoctor *: โดยเฉพาะอย่างยิ่ง สร้างเอาต์พุตของตัวเอง มีการรวมพื้นฐานบางอย่างกับ Sphinx และคุณสมบัติที่ดีบางอย่าง

Sphinx ส่วนใหญ่เป็นเครื่องมือในการจัดรูปแบบเอกสารที่เขียนขึ้นโดยไม่ขึ้นกับซอร์สโค้ดอย่างที่ฉันเข้าใจ

สำหรับการสร้างเอกสาร API จาก docstrings หลามเครื่องมือชั้นนำpdocและpydoctor นี่คือ pydoctor ของสร้างเอกสาร API สำหรับการบิดและบาซาร์

แน่นอนว่าหากคุณต้องการดู docstrings ในขณะที่คุณกำลังทำงานกับสิ่งต่างๆมีเครื่องมือบรรทัดคำสั่ง " pydoc " และhelp()ฟังก์ชันที่มีอยู่ในตัวแปลแบบโต้ตอบ

เป็นเครื่องมือที่เอกสารอื่น ๆ ที่ดีมากคือสฟิงซ์ มันจะใช้สำหรับเอกสาร python 2.6 ที่กำลังจะมาถึงและถูกใช้โดยdjangoและโครงการ python อื่น ๆ อีกมากมาย

จากเว็บไซต์สฟิงซ์:

• รูปแบบผลลัพธ์ : HTML (รวมถึงวิธีใช้ HTML ของ Windows) และ LaTeX สำหรับเวอร์ชัน PDF ที่พิมพ์ได้
• การอ้างอิงโยงอย่างกว้างขวาง : มาร์กอัปเชิงความหมายและลิงก์อัตโนมัติสำหรับฟังก์ชันคลาสศัพท์อภิธานศัพท์และข้อมูลที่คล้ายกัน
• โครงสร้างลำดับชั้น : คำจำกัดความง่ายๆของโครงสร้างเอกสารพร้อมลิงก์อัตโนมัติไปยังพี่น้องพ่อแม่และลูก
• ดัชนีอัตโนมัติ : ดัชนีทั่วไปและดัชนีโมดูล
• การจัดการโค้ด : การไฮไลต์อัตโนมัติโดยใช้ปากกาเน้นข้อความ Py เซ็กเมนต์
• ส่วนขยาย : การทดสอบข้อมูลโค้ดโดยอัตโนมัติการรวม docstrings จากโมดูล Python และอื่น ๆ