tl.pkg

tl.pkg היא תבנית לחבילת Python namespaced עם מסמכי הספינקס.
חבילה זו מייצרת את פריסת קבצים וספריות הבסיסית של חבילות Python עם תיעוד הספינקס וbuildout פיתוח. זה מורכב משני חלקים:
- תבנית paste.script שיוצרת מוכן מראש עבור חבילת פייתון שחיה ברמה אחת של מרחב, ו
- מודול פייתון שמשמש להגדרת תצורת הספינקס, יחד עם תלות החבילה הדרושה וכמה ערכות נושא.
החבילה עובדת עם פייתון 2.6 ו -2.7.
שימוש
כדי להפוך את תבנית פסטר זמינה, להתקין tl.pkg בי פסטר יכול למצוא אותו. לאחר מכן להפעיל פסטר:
& Nbsp;. פסטר ליצור TL-pkg <מרחב שמות> --template
זה יפיק מוכן מראש להפצת ביצה, להשלים עם תצורת zc.buildout, השלד של תיעוד חבילת הספינקס, ומאגר Mercurial יוזם. תצורת buildout היא ממוקדת בפיתוח, כך שזה יהיה להתקין testrunner בbin / בדיקה ובונת תיעוד בbin / doc.
כמה משתנים יתבקשו ל, ביניהם תיאור שורה אחת וכמה מילות מפתח לחבילה.
התאמה אישית
שלושה משתנים נוספים שפסטר מבקש ממך משמשים להתאמה אישית של שלד החבילה הוא יפיק. ייתכן שיש לי משתנה אלו ערכי ברירת מחדל שנקראים מבית $ / .tl-pkg.cfg קובץ בשם אם הוא קיים. הקובץ צריך לעקוב תחביר ini קובץ כפי שהובן על ידי ConfigParser של פייתון ומכיל סעיף אחד (עם שם שרירותי עד כה) שמגדיר כל אחד מהמשתנים הבאים:
מחבר: שם המלא שלך. זה יופיע במידע אודות החבילה והתיעוד, כמו גם בהודעות זכויות היוצרים של כל קבצים שנוצרו Python.
מחבר דואר אלקטרוני: כתובת דואר האלקטרוני שלך. זה מופיע גם במידע אודות החבילה ותיעוד.
bitbucket-שם: שם המשתמש שלך bitbucket. זה משמש לבניית כתובות האתרים השונות השייכים לפרויקט. נכון לעכשיו, ההנחה היא שהפרויקט מתארח ב< http://bitbucket.org/> וכתובות אתרים כל בנקודת המידע אודות חבילה ותיעוד לנכס את הדפים של פרויקט bitbucket ש.
תוכן חבילה
זה הוא להסביר את המטרה של הקבצים וספריות שנוצרו, יחד עם עצות על איזה קבצים לערוך מתי. קבצים רבים לא יהיו צורך בעריכה בכלל.
הפצת Python
setup.py: הגדרת החבילה ומטה. עדכון קובץ זה לפחות בכל פעם שמספר הגרסה של החבילה, תלות, נקודות כניסה לשנות.
<מרחב שם>: עץ קוד המקור של החבילה. אין לשנות קובץ __init__.py של חבילת המרחב שמא לא ניתן לייבא חבילות אחרות באותו המרחב.
מאגר Mercurial
.hg: מאגר Mercurial כבר יוזם כאשר החבילה נוצרה. הקבצים שנוצרו לא היו מחויבים עדיין.
.hg / hgrc: תצורת מאגר המצביע על כתובת האתר העתידית של החבילה בחלק אירוח Mercurial, אם בכלל. כמו כן, קובע שם המשתמש hg.
.hgignore: קבצים וספריות ליתעלמו מMercurial. זה כולל תצורה מקומית ודברים צפויים שיופקו על ידי buildout, תיעוד בונה או משחרר חבילה. היא אינה כוללת קבצים שנוצרו על ידי פייתון (כגון * .pyc), להפיץ (* .egg-info), או כלים אחרים כלליים יותר כמו העורך שלך, שאינם ספציפיים לפרויקט זה. דפוסים כאלה צריכים להיות בברירת המחדל שלך Mercurial רשימת ההתעלמות.
buildout פיתוח
bootstrap.py: יוצר את תסריט bin / buildout. להפעיל את זה עם אותו מתורגמן פייתון שbuildout צריך להשתמש. אין צורך אי פעם לערוך קובץ זה.
buildout.cfg: תצורת buildout עבודה שיוצרת רץ בדיקה ובונת תיעוד לחבילה. החבילה עצמה נכללת כביצה לפתח וbuildout מוגדר לשימוש בגרסות רק הצמיד של כל חבילות אחרות. לערוך את זה כדי להגדיר buildout הפיתוח הרשמי של החבילה אבל לשים התאמות מקומיות בlocal.cfg. pinnings הגרסה ללכת בגרסאות / versions.cfg בעוד סעיף הגרסאות של קובץ זה צריך לבטל pinnings של חבילות שהכריזו לפתח ביצים לפי סעיף buildout זה של אותו קובץ בלבד.
local.cfg: התאמות מקומיות של תצורת buildout כי הם לא מעניינים את מפתחים אחרים. זה שמתעלם ממנו על ידי Mercurial. אם תשנה את הקובץ זה, local.cfg -c bin / buildout לרוץ מכאן ואילך. גם אם זה נשמע מסורבל בהתחלה, שמירה על התצורה שאינה מקומית בbuildout.cfg ותחת בקרת גרסאות חשובה למקרי שימוש כגון בדיקת החבילה בשרת רציפה אינטגרציה.
גרסאות / versions.cfg:
& Nbsp; הגרסה מצמידה לכל חבילות בשימוש על ידי buildout שאינם חלק מארגז הכלים Zope. הגרסה של tl.pkg אשר נדרש לבניית התיעוד הוצמדה לאותה הגרסה שיצרה את קבצי החבילה. בעת שדרוג tl.pkg מאוחר יותר, גרסה זו תולה צריכה להיות מעודכנת יחד עם כל קבצים שהשתנו בתבנית החבילה בין הגרסאות. ערוך קובץ זה להצמיד את הגרסאות של כל ביצים הנדרשות על ידי החבילה שלך או buildout שלך.
גרסאות / ZTK-גרסאות-X.Y.Z.cfg:
& Nbsp; שחרור קבוע של ערכת הכלים Zope, כלול בpinnings הגרסה שלנו. שמירת עותק מקומי של זה מאפשר בניית buildout ללא גישה לרשת. אין לערוך קובץ זה.
תיעוד חבילה כללי
ישנם מספר של קבצי טקסט ניתן למצוא בספרייה ברמה העליונה של החבילה המכיל חתיכות סטנדרטית של התיעוד ולכן צפויים באותו מקום ותחת השמות שלהם בפרט, ואשר צריך להיות עצמאי נגיש של הספינקס. קבצים אלה צריכים להיות טקסט תקף מחדש כפי שהם מעובדים על-ידי הספינקס בעת בנייה בתיעוד המלא, פרט לטקסט הודעת זכויות יוצרים ורישיון הנכללים מילה במילה.
README.txt: סקירה כללית של המטרה, תוכן של החבילה ושימוש בו תהיה חלק מדף PyPI ושל דף האינדקס של התיעוד. זה צריך להיות כל הזמן למעלה עדכני עם תוכן האריזה בכל העת.
CHANGES.txt: שינוי היומן שצריך להיות מעודכנים עם כל שינויים בחבילה שהם רלוונטיים למשתמשים של החבילה. הפורמט של הקובץ מובן על ידי zest.releaser והגרסה הנוכחית של זה (כלומר הגרסה "קצה" במאגר Mercurial הציבורי) יהיה הצביעו מהעמוד PyPI ותיעוד החבילה הבנויה.
ABOUT.txt: כמה עצות על החבילה ומחבריו, כגון כתובת דואר האלקטרוני של זה האחרון וכתובות האתרים של התיעוד של החבילה, דף PyPI, גשש נושא ואת קוד מקור, כמו גם את היומן הנוכחי. הנחה היא תיעוד שיהיה יפורסם הן בPyPI וב< http://readthedocs.org/>; אתה צריך לוודא להשתמש בכתובות האתרים בהתאמה הנכונות יוקצו לפרויקט שלך.
COPYRIGHT.txt: מידע על זכויות יוצרים חבילה: בעל זכויות היוצרים כוללים בשנות זכויות היוצרים ועוד כמה עצות על רישיון שימוש, המהווה את הרישיון הציבורי Zope, גרסת 2.1 כברירת מחדל. לערוך את זה לפחות לעדכן השנים.
License.txt: עותק של הטקסט הרשמי של רישיון שימוש. אל תערכו זה, חוץ מלהחליף אותו לרישיון שונה.
תיעוד מלא, נבנה באמצעות הספינקס
doc: כל מה שהוא רק רלוונטי לתיעוד שנוצר-הספינקס. אנו משתמשים בסיומת .txt לקבצי קלט הספינקס. בעוד מספר המוסכמות קיים לתכולת ספריית doc, שום דבר רע לא יקרה לשאר החבילה אם תשנו אותו באופן חופשי; רק לוודא שהוא נשאר קלט הספינקס בתוקף.
doc / conf.py: תצורת הספינקס. בעיקרון כל ערכי תצורת מעקב מוסכמות ולכן מיובאים מtl.pkg, כך שאתה חייב לשמור על היבוא והקריאה של tl.pkg.sphinxconf ללא פגע. אתה צריך לערוך את הקובץ אם אתה רוצה לשנות משהו על מטה-נתונים או את המראה של התיעוד רק עבור חבילה זו. עדכונים לאמנות לתיעוד שנוצר-הספינקס יירכשו על ידי שדרוג tl.pkg.
העמוד הראשי של התיעוד: doc / index.txt. הוא כולל סקירה כללית של החבילה מקובץ README.txt ברמה העליונה ותוכן עניינים מצביע על הסעיפים בתיעוד המלא. אלה כוללים תיעוד API שנוצר, מידע meta כמה על החבילה ואת יומן השינוי. ערוך קובץ זה אם ברצונך להוסיף קטעים ברמה העליונה, למשל.
doc / narrative.txt:
& Nbsp; מסמך השורש של תיעוד חבילת הנרטיב. זה נועד כדי לאסוף את כל קבצי doc מבחן שמתגוררים בין מודולים Python בעץ המקור שלך. אתה צריך לפרט את הקבצים תחת הוראת toctree, שמות המסמך שלהם להיות בתבנית <מרחב שם> -. <שם קובץ> (ללא סיומת .txt). רישום קובץ הדוגמא הגיב החוצה כלול.
doc / api.txt: מסמך השורש של תיעוד API שנוצר. API מתועד למחצה באופן אוטומטי שביש לך רשימה בקובץ זה, תחת הוראת autosummary, כל המודולים להיות מתועדים, וזה קורה באופן אוטומטי מכאן ואילך. רישום הדוגמא מודול הגיב החוצה כלול.
doc / overview.txt:
& Nbsp; בדל לכלול את הקובץ ברמה העליונה README.txt. אין צורך לערוך את הקובץ הזה.
doc / about.txt: מידע Meta על החבילה, הקבצים ברמה העליונה ABOUT.txt, COPYRIGHT.txt, וLicense.txt שילוב. אתה לא צריך לערוך את הקובץ הזה.
doc / changes.txt:
& Nbsp; בדל לכלול CHANGES.txt הקובץ ברמה העליונה. אין צורך לערוך את הקובץ הזה.
doc / requirements.pip:
& Nbsp; רישום של ביצי פייתון (מלבד הספינקס עצמו) דרוש לבנייה בתיעוד. זה נועד לבנייה בתיעוד ב< http://readthedocs.org/>. אתה צריך להיות ברשימה לבנה עימם על מנת שתוכל להשתמש באמנות המיושמות על ידי tl.pkg. ערוך קובץ זה בכל פעם שהתלות של חבילת התיעוד שלך לשנות; אתה לא יכול להשתמש תוספות ביצה כאן.
בניית התיעוד המלא
תצורת buildout נוצרה מתקינה תסריט בbin / doc שקורא הספינקס לבנות התיעוד. כדי להפעיל script זה, ספריית העבודה הנוכחית שלך חייבת להיות שורש החבילה. התסריט יהיה לשים את התיעוד המובנה בתוך מבנה / doc / (יחסית לספרייה ברמה העליונה של החבילה). אפשרויות עברו לbin / doc תועברנה לפקודת ספינקס-לבנות בסיס, אבל שימו לב שטיעוני positional לא יעבדו.
ערכי תצורה הספינקס
כברירת מחדל, מספר הרחבות הספינקס מופעל, כך שייתכן שתרצה להגדיר את אלה, בנוסף למשתני הספינקס ליבה:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
אתה יכול לעקוף את ברירות המחדל מtl.pkg פשוט על ידי הגדרת המשתנים המתאימים בconf.py. שלך הקריאה של tl.pkg.sphinxconf.set_defaults צריכה לקרות בסוף:
source_suffix = '.foo'
tl.pkg.sphinxconf יבוא
tl.pkg.sphinxconf.set_defaults ()
לעומת זאת, sphinxconf מנסה להשתמש במשתנים מconf.py לחשב ערכים. אם צוינו המשתנים הללו, שחייבים להיעשות גם לפני set_defaults נקרא. נכון לעכשיו, את המשתנים הבאים מוכרים:
_year_started: ערך אופציונאלי לשנה הפרויקט החל. ברירת מחדל זה לשנה הנוכחית (בזמן בניית תיעוד), אבל אם זה מצוין ושונה מהשנה הנוכחית, הוא משמש לבניית הודעת זכויות יוצרים כמו "מחבר 2001-2012".
_flattr_url: אם צוין, זה הנחה הוא להיות הכתובת של דבר flattr לפרויקט זה ולחצני תרומת flattr יופיע בחלקו העליון של עמוד התפריט של התיעוד המלא. כדי להוסיף לחצן flattr לדף PyPI, uncomment סעיף "תמיכה בפרויקט" בABOUT.txt ולמלא גם שם ב- URL.
_issuetracker_offline:
& Nbsp; אם נקבע לערך אמיתי, שילוב bitbucket של האינטגרציה sphinxcontrib-issuetracker יהיה שונה, כך שהוא לא ינסה לגשת לשרת בעת בנייה בתיעוד ובריצת הספינקס נשאר עצמאי של גישה לרשת. (אינטגרציה עם גששים אחרים לא טופלה עד כה.) זו תשבית חלק מהפונקציונליות של האינטגרציה הגשש, אך נשמרה, למשל, את יכולתו של הארכת issuetracker להכיר מספרי נושא טקסט רגיל.
לבסוף, מודול tl.pkg.sphinxconf מגדיר פונקציה שאתה יכול לקרוא לרישום מודולים מדומים אם התיעוד הוא להיות בנוי על מערכת כגון שלא ניתן להתקין קוד מסוים (כמו מודולים מיושם ב- C):
tl.pkg.sphinxconf.register_mock_modules (, 'gobject' 'cairo', 'gtk')

דרישות :