כיצד להגדיר את ספינקס כדי לתעד את קוד הפייתון שלך

ספינקס הוא אחד הכלים הפופולריים ביותר להפקת תיעוד. בכל רחבי קהילת Python, מפתחים משתמשים בתוכנת הקוד הפתוח החינמית הזו. זה יכול לחלץ טקסט ישירות מהקוד או מקבצי הסימון שלך ואז להשתמש בו כדי ליצור תיעוד בפורמטים שונים כגון טקסט רגיל, HTML, PDF ו-EPUB.

הגדרת ספינקס

לפני שתגדיר את Sphinx, עיין במה שהוא עושה ובכמה מהתכונות העיקריות שלו.

מהו ספינקס ומה הוא עושה?

כאמור, ספינקס הוא מחולל תיעוד. כברירת מחדל, הוא משתמש בשפת הסימון reStructuredText (RST), אך באמצעות הרחבות של צד שלישי, הוא יכול גם השתמש ב-Markdown, שפת הסימון הפופולרית של טקסט רגיל. לאחר מכן, הוא ממיר את קובצי ה-RST או הסימון ל-HTML, PDF, דפים ידניים או פורמטים אחרים שאתה מעדיף.

חלק מהתכונות שספינקס כולל הן:

• יכולת הפקת תיעוד מקוד.
• יכולת הצלבה של דפי מסמכים שונים באמצעות קישורים אוטומטיים לפונקציות, מחלקות, ציטוטים ומונחי מונחים.
• הדגשת תחביר עבור בלוקי קוד.
• תמיכה בנושאים שיכולים לשנות את המראה והתחושה של המסמכים.
• הגדרה קלה של עץ המסמכים באמצעות תוכן עניינים.
instagram viewer
• יכולת שילוב עם הרחבות של צד שלישי כדי להוסיף פונקציונליות נוספת למסמכים כגון בדיקת קטעי קוד.

התקנת ספינקס

לפני התקנת Sphinx, ודא שיש לך Python 3 מותקן בסביבת הפיתוח שלך. לאחר מכן תוכל להשתמש במנהל החבילות pip כדי להתקין את Sphinx על ידי הפעלת הפקודה הבאה בטרמינל שלך:

pip להתקין ספינקס

פעולה זו תוריד ותתקין את Sphinx והתלות שלו.

לאחר ההתקנה, הפעל את הדברים הבאים בשורת הפקודה.

sphinx-build --גרסה

אם הכל עבד כשורה, אתה אמור לראות את מספר הגרסה של חבילת Sphinx שזה עתה התקנת.

יצירת פרויקט ספינקס חדש

לאחר שהתקנת את Sphinx, נווט אל ספריית העבודה שלך והפעל את הפקודה sphinx-quickstart כדי ליצור פרויקט Sphinx חדש.

ספינקס-התחלה מהירה

פקודה זו תנחה אותך לענות על סדרה של שאלות כיצד להגדיר את פרויקט הספינקס שלך. אתה יכול לציין את שם הפרויקט ולהשתמש באפשרויות ברירת המחדל עבור השאלות האחרות. בעתיד, ייתכן שתרצה להתאים אישית את התגובות על סמך הפרויקט שלך.

אם תפרט את התוכן של הספרייה שלך, תראה שהפקודה הזו יוצרת עבורך כמה קבצים. ה-conf.py מכיל את ערכי התצורה וה-index.rst משמש כדף הפתיחה של התיעוד שלך. ספריית ה-build תארח את התיעוד שנוצר, וספינקס משתמש ב-Makefile (make.bat ב-Windows) כדי לבנות את התיעוד.

כתיבת תיעוד באמצעות ספינקס

הקובץ index.rst בשורש הספרייה שלך הוא דף הבית של היישום שלך. אז, פתח אותו עם עורך טקסט כמו VS Code - או כל עורך קוד טוב וחינמי אחר- כדי לערוך אותו.

אתה יכול לשנות את ה-index.rst כראות עיניך, אבל דבר אחד שהוא צריך לפחות הוא הוראת השורש toctree (עץ תוכן העניינים). זה חיוני מכיוון שהוא מחבר מספר קבצים להיררכיה אחת של מסמכים.

כדי להוסיף תיעוד לקובץ index.rst, אתה יכול להשתמש בסימון RST.

כדוגמה, שקול קובץ index.rst עבור מודול math_utils. קובץ זה עשוי לכלול סקירה קצרה של מטרת המודול ותוכן עניינים המקשר לדפים אחרים של התיעוד.

ברוכים הבאים ל- Math Utils
.. toctree::
 :maxdepth: 2
מתחילים

כדי להשתמש במודול זה, תצטרך את הדברים הבאים:
* Python מותקן.
* עורך טקסט
כלי מתמטיקה

מודול `math-utils` מספק פונקציות מתמטיות בסיסיות כמו חיבור ו
חִסוּר.

ניתן להוסיף עוד קבצי .rst לפי הצורך. לדוגמה, אתה יכול ליצור מדריך תרומה בקובץ בשם contributing.rst המכיל את הנחיות התרומה הבאות.

מדריך תורם
נשמח לתרומות לפרויקט שלנו! הנה כמה הנחיות עבור
תורם:
- מזלג את הפרויקט ב-GitHub.
- בצע את השינויים שלך בסניף חדש.
- כתוב מבחנים כדי לוודא שהשינויים שלך פועלים כהלכה.
- שלח בקשת משיכה עם השינויים שלך.
- בצע את כל השינויים המבוקשים.
תודה על התרומה!

לאחר מכן תוכל לקשר את הקובץ הזה מ-index.rst על ידי הוספת קטע חדש להנחיית toctree:

.. toctree::
 :maxdepth: 2
 :caption: תוכן העניינים

 תורם

זה יוצר פריט חדש בשם תורם בתוכן העניינים שלוקח את המשתמש לדף התרומה כאשר לוחצים עליו.

לאחר שכתבת את התיעוד, השלב הבא הוא לבנות אותו. כאן, בניית התיעוד פירושה יצירת דפי HTML, מדריך או PDF מקובצי RST.

בניית התיעוד

כדי לבנות את התיעוד באמצעות Sphinx, תצטרך להפעיל את הפקודה make html בשורש התיקיה שלך בה נמצא ה-makefile.

לעשות html

אתה אמור לראות את קבצי ה-HTML בתיקיית ה-build. אם היו שגיאות במהלך הבנייה, Sphinx יודיע לך בטרמינל.

כדי להציג את התיעוד, פתח את הקובץ index.html בדפדפן שלך:

אתה אמור להיות מסוגל לנווט אל המדריך התורם מתוכן העניינים.

התאמה אישית של התיעוד

נכון לעכשיו, לתיעוד יש קצת סטיילינג בסיסי. אם אתה רוצה להתאים את זה, אולי על ידי הוספת צבעי המותג שלך, או אפילו הוספת מצב כהה, אתה יכול להתקין ולהשתמש אחרים ערכות נושא מובנות או צור ערכת נושא מותאמת אישית משלך.

כדי להדגים, נסה לשנות את הנושא לזה שנקרא טבע:

1. פתח את קובץ התצורה של ספינקס conf.py בספריית פרויקט הספינקס שלך.
2. חפש את השורה המגדירה את אפשרות html_theme ושנה אותה לטבע
3. שמור את קובץ התצורה ובנה מחדש את התיעוד כדי לראות את השינויים שלך.

כך אמור להיראות דף הבית של התיעוד.

אם אינך רוצה להשתמש בערכות הנושא המובנות, אתה תמיד יכול להשתמש ב-a נושא ספינקס של צד שלישי במקום זאת.

תיעוד הקוד שלך באמצעות Docstrings

Sphinx מייצר את תיעוד Python שלך מטקסט שאתה כותב בקובצי RST. למרות שזה מספיק במקרים מסוימים, ייתכן שתרצה להשתמש במחרוזות docstrings בקוד שלך לזה ברמת המודול.

מחרוזות Docstrings חיות ישירות בתוך קבצי המקור של הפרויקט שלך. הם מאפשרים לך לתאר מה הקוד עושה, לספק דוגמאות ואפילו ליצור מבחנים עבור הדוגמאות הללו. לאחר שכתבת מחרוזות docstrings, תוכל ליצור מהם תיעוד באמצעות Sphinx.