tl.pkg

وtl.pkg هو قالب لحزمة بايثون namespaced مع مستندات أبو الهول.
هذه الحزمة يولد الملف والدليل الأساسي تصميم حزم بيثون مع وثائق أبو الهول وbuildout التنمية. وهو يتألف من جزأين:
- قالب paste.script أن يخلق النمطي للحصول على حزمة بيثون أن يعيش في مستوى واحد من مساحة الاسم، و
- وحدة بيثون الذي يستخدم لتكوين أبو الهول، جنبا إلى جنب مع تبعيات حزمة الضرورية وبعض تطبيق السمات.
حزمة يعمل مع بيثون 2.6 و 2.7.
استعمال
لجعل قالب المقرب المتاحة، تثبيت tl.pkg حيث المقرب يمكن العثور عليه. ثم قم بتشغيل المقرب:
على & nbsp؛. المقرب خلق --template TL-PKG <اسم_المشروع>
هذا وسوف تولد النمطي لتوزيع البيض، مع استكمال التكوين zc.buildout، والهيكل العظمي وثائق حزمة أبو الهول، ومستودع زئبقي initialised. ويستهدف تكوين buildout في التنمية، لذلك سوف تثبيت testrunner في بن / اختبار وباني الوثائق في بن / DOC.
سوف يطلب بضعة المتغيرات ل، من بينها وصف من سطر واحد وبعض الكلمات الرئيسية للحزمة.
إضفاء الطابع الشخصي
وتستخدم ثلاثة متغيرات أكثر التي المقرب يسألك عن لإضفاء الطابع الشخصي على هيكل عظمي حزمة فإنه سيتم إنشاء. وقد يكون لهذه المتغيرات القيم الافتراضية التي يتم قراءتها من ملف باسم $ HOME / .tl-pkg.cfg إذا كان موجودا. يحتاج الملف إلى اتباع جملة رسائل كتبها هذا المؤلف ملف كما يفهمه ConfigParser بايثون ويحتوي على مقطع واحد (مع اسم عشوائية حتى الآن) أن يحدد أي من المتغيرات التالية:
المؤلف: اسمك الكامل. هذا وسوف تظهر في البيانات الوصفية حزمة وثائق وكذلك في إشعارات حقوق التأليف والنشر من أي ملفات بيثون ولدت.
المؤلف البريد الإلكتروني: عنوان البريد الإلكتروني الخاص بك. هذا يظهر في كل من الفوقية حزمة وثائق.
bitbucket اسم: bitbucket اسم المستخدم الخاص بك. ويستخدم هذا لبناء عناوين مختلفة تابعة للمشروع. في الوقت الحاضر، فإن الافتراض هو أن المشروع مستضافة في وأي عناوين المواقع في نقطة الفوقية حزمة وثائق لتستولي صفحات هذا المشروع bitbucket.
محتويات العبوة
هذا هو لشرح الغرض من الملفات والدلائل ولدت، جنبا إلى جنب مع المشورة بشأن الملفات التي لتعديل متى. لن تحتاج العديد من الملفات المراد تحريرها على الإطلاق.
توزيع بيثون
setup.py: تعريف حزمة والبيانات الوصفية. تحديث هذا الملف على الأقل كلما عدد حزمة في الإصدار، والتبعيات، تتغير نقاط الدخول.
: شجرة الشفرة المصدرية من الحزمة. لا تقم بتعديل ملف __init__.py حزمة مساحة الاسم لئلا حزم أخرى في مساحة الاسم نفسه لا يمكن استيرادها.
مستودع الزئبقي
.hg: يتم initialised مستودع زئبقي بالفعل عندما تم إنشاء الحزمة. لم تلتزم الملفات التي تم إنشاؤها بعد.
.hg / hgrc: مواصفات مستودع الذي يشير إلى URL في المستقبل من الحزمة في بعض استضافة زئبقي، إن وجدت. ويحدد أيضا الزئبق اسم المستخدم الخاص بك.
.hgignore: الملفات والدلائل بأن يتجاهلك الآخرون من قبل زئبقي. ويشمل هذا التكوين المحلي والاشياء المتوقع أن تولدها buildout والتوثيق يبني أو النشرات الحزمة. أنها لا تتضمن الملفات التي تم إنشاؤها من قبل بيثون (مثل * .pyc) وتوزيع (* .egg-المعلومات)، أو غيرها من أدوات أكثر عمومية مثل محرر الخاص بك، والتي هي ليست محددة لهذا المشروع. وينبغي أن تكون هذه الأنماط على تجاهل الافتراضي زئبقي القائمة.
buildout التنمية
bootstrap.py: يخلق النصي بن / buildout. تشغيل هذا مع نفس بيثون مترجم التي يجب أن يستخدمها buildout. لا حاجة إلى أي وقت مضى تحرير هذا الملف.
buildout.cfg: A العمل التكوين buildout أن يخلق عداء اختبار وباني وثائق للحزمة. يتم تضمين حزمة نفسها على أنها تطوير البيض ويتم تكوين buildout استخدام إصدارات معلقة فقط من أي حزم أخرى. تعديل هذه لتكوين buildout الإنمائية الرسمية حزمة ولكن وضع تخصيصات المحلية في local.cfg. pinnings نسخة تذهب في الإصدارات / versions.cfg بينما القسم إصدارات هذا الملف يجب التراجع عن pinnings من الحزم التي تم تعريفها تطوير البيض من قبل القسم buildout نفس هذا الملف فقط.
local.cfg: تخصيصات المحلية من التكوين buildout التي لا مصلحة لمطورين آخرين. يتم تجاهل هذا عن طريق زئبقي. إذا قمت بتغيير هذا الملف، قم بتشغيل بن / buildout local.cfg -c منذ ذلك الحين. في حين أن هذا قد يبدو مرهقا في البداية، والحفاظ على التكوين غير المحليين في 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 والإصدار الحالي منه (أي "طرف" الإصدار في مستودع زئبقي العام) سيتم أشار إلى من الصفحة PyPI والوثائق حزمة بناؤها.
ABOUT.txt: بعض المؤشرات حول حزمة واضعيه، مثل عنوان البريد الإلكتروني هذا الأخير وعناوين المواقع من وثائق الحزمة، صفحة PyPI، مخرج تعقب ورمز مصدر فضلا عن السجل الحالي. ومن المفترض سيتم ينشر هذه الوثائق سواء في PyPI وفي . يجب عليك التأكد من استخدام عناوين المواقع منهما الصحيحة المسندة إلى المشروع.
COPYRIGHT.txt: معلومات حقوق النشر لحزمة: صاحب حقوق الطبع والنشر بما في ذلك السنوات حقوق النشر وبعض النصائح حول الترخيص المستخدمة، وهو الترخيص العام Zope، الإصدار 2.1 افتراضيا. تعديل هذا على الأقل لتحديث عاما.
LICENSE.txt: نسخة من النص الرسمي للرخصة المستخدمة. لا تعديل هذه إلا لتستبدلها على ترخيص مختلفة.
وثائق كاملة، تم إنشاؤها باستخدام أبو الهول
وثيقة: كل ما له صلة فقط إلى وثائق ولدت أبو الهول. نحن نستخدم لاحقة. TXT ملفات الإدخال أبو الهول. في حين وجود عدد من الاتفاقيات لمحتويات الدليل وثيقة، لا شيء سيئ سيحدث لبقية حزمة إذا كان يمكنك تعديله بحرية. فقط للتأكد من أنها لا تزال مدخلات أبو الهول صالح.
وثيقة / conf.py: مواصفات أبو الهول. في الأساس كافة القيم التكوين متابعة الاتفاقيات وبالتالي يتم استيرادها من tl.pkg، لذلك يجب الحفاظ على الاستيراد والاحتجاج tl.pkg.sphinxconf سليمة. سيكون لديك لتحرير هذا الملف إذا كنت ترغب في تغيير شيء عن الفوقية أو ظهور وثائق فقط لهذه الحزمة. سيتم الحصول على التحديثات إلى اتفاقيات للتوثيق ولدت أبو الهول-عن طريق رفع مستوى tl.pkg.
وثيقة / index.txt: الصفحة الأولى من الوثائق. وهو يتضمن نظرة عامة حزمة من README.TXT الملف ذات المستوى الأعلى وجدول المحتويات لافتا إلى أقسام من وثائق كاملة. وتشمل هذه الوثائق API ولدت، بعض المعلومات الوصفية حول حزمة وسجل التغيير. عدل هذا الملف إذا كنت ترغب في إضافة أقسام المستوى الأعلى، على سبيل المثال.
وثيقة / narrative.txt:
على & nbsp؛ الوثيقة الجذر من وثائق حزمة السرد. ويهدف هذا لجمع أي ملفات DOC-الاختبار الموجودة بين وحدات بيثون في شجرة المصدر. تحتاج لسرد الملفات تحت التوجيه toctree، وأسماء وثيقتهم يجري من نمط - (بدون لاحقة. TXT). يتم تضمين قائمة ملف سبيل المثال علق المغادرة.
وثيقة / api.txt: وثيقة الجذر من وثائق API إنشاؤها. تم توثيق API شبه تلقائيا في أن لديك لسرد في هذا الملف، في ظل التوجيه autosummary، جميع وحدات لتكون موثقة، والذي يحدث تلقائيا منذ ذلك الحين. يتم تضمين قائمة سبيل المثال وحدة علق المغادرة.
وثيقة / overview.txt:
على & nbsp؛ وكعب لتشمل الملف المستوى الأعلى README.TXT. لا حاجة لتحرير هذا الملف.
وثيقة / about.txt: المعلومات الوصفية حول حزمة، والجمع بين الملفات على مستوى عال ABOUT.txt، COPYRIGHT.txt، وLICENSE.txt. لن تحتاج إلى تحرير هذا الملف.
وثيقة / changes.txt:
على & nbsp؛ وكعب لتشمل CHANGES.txt ملف على مستوى عال. لا حاجة لتحرير هذا الملف.
وثيقة / requirements.pip:
على & nbsp؛ وهناك قائمة من البيض بيثون (بخلاف أبو الهول نفسه) المطلوبة لبناء الوثائق. ويهدف هذا لبناء وثائق في . سوف تحتاج إلى أن تكون اللائحة البيضاء معهم من أجل أن تكون قادرة على استخدام الاتفاقيات التي تنفذها tl.pkg. عدل هذا الملف كلما تغير تبعيات حزمة الوثائق الخاصة بك. لا يمكنك استخدام البيض اشياء هنا.
بناء على الوثائق الكاملة
التكوين buildout ولدت بتثبيت برنامج نصي على بن / وثيقة تدعو أبو الهول لبناء الوثائق. لتشغيل هذا البرنامج النصي، يجب أن يكون دليل العمل الحالي جذور الحزمة. البرنامج النصي وضع بنيت الوثائق إلى بناء / وثيقة / (نسبة إلى دليل المستوى الأعلى في الحزمة). سيتم تمرير الخيارات التي تم تمريرها إلى بن / DOC إلى الكامنة وراء قيادة أبو الهول والبناء، ولكن لاحظ أن الحجج الموضعية لن تعمل.
أبو الهول قيم التكوين
افتراضيا، يتم تمكين عدد من ملحقات أبو الهول، لذلك قد ترغب في تكوين هذه بالإضافة إلى المتغيرات أبو الهول الأساسية:
- 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: إذا تم تحديدها، ويفترض أن تكون هذه هي URL من شيء flattr لهذا المشروع وأزرار التبرع flattr سوف تظهر في الجزء العلوي من العمود القائمة من وثائق كاملة. لإضافة زر flattr إلى صفحة PyPI، غير تعليق على "دعم مشروع" البند في ABOUT.txt وملء URL هناك أيضا.
_issuetracker_offline:
& nbsp؛ إذا لتعيين القيمة الحقيقية، سيتم تعديل دمج bitbucket من التكامل sphinxcontrib-issuetracker بحيث لن محاولة الوصول إلى الخادم عند بناء الوثائق وعلى المدى أبو الهول تبقى مستقلة عن الوصول إلى الشبكة. (التكامل مع بتتبع أخرى لم يتم اتخاذ رعاية حتى الآن.) سيؤدي ذلك إلى تعطيل بعض الوظائف من التكامل تعقب لكن الاحتفاظ بها، على سبيل المثال، القدرة على تمديد issuetracker الاعتراف قضية أرقام نص عادي.
وأخيرا، تحدد وحدة tl.pkg.sphinxconf وظيفة التي يمكنك الاتصال لتسجيل وحدات وهمية إذا كانت الوثائق هي أن تكون مبنية على نظام مثل لا يمكن تثبيت كود معين (مثل وحدات نفذت في C):
tl.pkg.sphinxconf.register_mock_modules ('القاهرة'، 'gobject'، 'جتك')

المتطلبات:

بيثون