tl.pkg

در tl.pkg یک الگو برای یک بسته namespaced پایتون با اسناد مجسمه ابوالهول است.
این بسته تولید فایل و دایرکتوری عمومی طرح از بسته های پایتون با مستندات مجسمه ابوالهول و buildout توسعه است. این دو قسمت تشکیل شده:
- قالب paste.script که boilerplate برای یک بسته پایتون که در یک سطح فضای نام زندگی می کند ایجاد و
- یک ماژول پایتون است که برای پیکربندی مجسمه ابوالهول، همراه با وابستگی بسته لازم و برخی از قالب دهی.
بسته با پایتون 2.6 و 2.7 کار می کند.
استفاده
برای اینکه قالب paster های موجود، نصب tl.pkg که در آن paster می توانید آن را پیدا کنید. پس از آن اجرا paster:
& nbsp؛ در. paster ایجاد --template TL-PKG <فضای نام>
با این کار boilerplate برای توزیع تخم مرغ، کامل با پیکربندی zc.buildout، اسکلت اسناد و مدارک بسته مجسمه ابوالهول، و یک مخزن جیوه راه اندازی تولید کند. پیکربندی buildout در توسعه هدفمند، پس از آن خواهد testrunner در بن / آزمون و سازنده مستند در بن / توضیحات نصب کنید.
چند متغیر خواهد، باعث در میان آنها توضیحات یک خطی و برخی از کلمات کلیدی برای بسته بندی.
شخصی
سه متغیر تر است که paster شما برای پرسد استفاده می شود به فرد اسکلت بسته آن تولید خواهد شد. این متغیرها ممکن است مقادیر پیش فرض که از یک فایل به نام $ HOME / .tl-pkg.cfg به عنوان خوانده شده صورت وجود داشته باشد. فایل نیاز به پیروی نحو INI-فایل که توسط ConfigParser پایتون درک و شامل یک بخش (با نام دلخواه تا کنون) که تعریف هر یک از متغیرهای زیر است:
نویسنده: نام و نام خانوادگی شما. این در ابرداده بسته و اسناد و همچنین در اعلامیه حقوق قانونی هر گونه فایل پایتون تولید ظاهر خواهد شد.
نویسنده-ایمیل: آدرس پست الکترونیکی شما. این به نظر می رسد هر دو در ابرداده بسته و اسناد.
bitbucket نام: bitbucket نام کاربر شما. این استفاده می شود برای ساخت URL های مختلف متعلق به پروژه می باشد. در حال حاضر، فرض بر این است که این پروژه در میزبانی و هر گونه آدرس ها در ابرداده بسته و اسناد نقطه مناسب صفحات که پروژه bitbucket.
محتویات بسته
این است برای توضیح هدف از فایل های تولید شده و دایرکتوری ها، همراه با مشاوره در مورد فایل ها را ویرایش و هنگامی که. بسیاری از فایل های نمی خواهد نیاز به در تمام ویرایش شده.
توزیع پایتون
setup.py: تعریف بسته و ابرداده. به روز رسانی این فایل حداقل هر زمان که شماره نسخه بسته است، وابستگی، نقاط ورود تغییر دهید.
<فضای نام>: درخت کد منبع بسته. آیا فایل __init__.py بسته فضای نام در تغییر دهید تا مبادا بسته های دیگر در فضای نام یکسان نیست می تواند وارد شود.
مخزن جیوه
.hg: مخزن جیوه در حال حاضر راه اندازی وقتی که بسته ایجاد شده است. فایل های تولید شده هنوز متعهد نشده است.
.hg / hgrc: پیکربندی مخزن که اشاره به URL آینده بسته در برخی از میزبانی جیوه، در صورت وجود. همچنین این مجموعه نام کاربری جیوه کنید.
.hgignore: فایل ها و دایرکتوری که باید توسط جیوه استفاده کنه. این شامل پیکربندی محلی و مسائل انتظار می رود که توسط buildout، اسناد ایجاد یا منتشر بسته شود. این کار فایل های تولید شده توسط پایتون (مانند * * * * .pyc) را شامل نمی شود، پخش (* .egg-اطلاعات)، و یا دیگر ابزار به طور کلی بیشتر شبیه به ویرایشگر خود را، که خاص این پروژه نیست. چنین الگوهای باید در پیش فرض خود را جیوه لیست.
buildout توسعه
bootstrap.py: ایجاد اسکریپت بن / buildout. اجرای این با مفسر پایتون همان است که buildout باید استفاده کنید. بدون نیاز به تا کنون ویرایش این فایل.
buildout.cfg: پیکربندی buildout کار که یک دونده آزمون و سازنده مستندات مربوط به بسته ایجاد می کند. بسته خود را به عنوان یک تخم مرغ توسعه شامل و buildout پیکربندی شده است به استفاده از نسخه های تنها دوخته هر بسته های دیگر. ویرایش این پیکربندی buildout توسعه رسمی بسته است اما قرار customisations محلی در local.cfg. pinnings نسخه در نسخه های به / versions.cfg در حالی که بخش نسخه این فایل را باید تنها pinnings از بسته هایی که اعلام می شوند توسعه تخم مرغ توسط بخش buildout این فایل همان لغو.
local.cfg: customisations محلی پیکربندی 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 و در چاپ. شما باید مطمئن شوید که به استفاده از URL های صحیح مربوطه اختصاص یافته به پروژه شما.
COPYRIGHT.txt: اطلاعات کپی رایت برای بسته بندی: صاحب حقوق قانونی از جمله سال کپی رایت و برخی از مشاوره در مورد مجوز استفاده می شود، که مجوز Zope، نسخه 2.1 به طور پیش فرض. ویرایش این حداقل برای به روز رسانی سال.
LICENSE.txt: یک کپی از متن رسمی مجوز استفاده می شود. آیا ویرایش کنید این را جز به آن ازای مجوز های مختلف.
مستندات کامل، ساخته شده با استفاده از مجسمه ابوالهول
توضیحات: همه چیز این است که تنها به مستندات مجسمه ابوالهول تولید مرتبط. ما با استفاده از کلیپ برد چند منظوره پسوند برای فایل های ورودی مجسمه ابوالهول. در حالی که تعدادی از کنوانسیون برای محتویات دایرکتوری توضیحات وجود داشته باشد، هیچ چیز بد را به بقیه از بسته اگر شما آن را تغییر دهید آزادانه اتفاق می افتد. فقط مطمئن شوید که آن ورودی مجسمه ابوالهول معتبر باقی مانده است.
توضیحات / conf.py: پیکربندی مجسمه ابوالهول. در واقع تمام ارزش های پیکربندی را دنبال کنوانسیون و بنابراین از tl.pkg وارد، بنابراین شما باید واردات و نیایش از tl.pkg.sphinxconf دست نخورده نگه دارید. شما باید برای ویرایش این فایل اگر شما می خواهید به تغییر چیزی در مورد ابرداده و یا ظاهر اسناد فقط برای این بسته. به روز رسانی به کنوانسیون مدارک مجسمه ابوالهول تولید خواهد شد ارتقاء tl.pkg به دست آورد.
توضیحات / index.txt: صفحه اول مستندات. این شامل بررسی اجمالی بسته از فایل Readme.txt در سطح بالا و یک جدول از محتویات با اشاره به بخش مستندات کامل. این شامل مستندات API تولید شده، برخی از اطلاعات متا در مورد بسته بندی و تغییرات این. ویرایش این پرونده اگر شما می خواهید برای اضافه کردن بخش در سطح بالا، به عنوان مثال.
توضیحات / narrative.txt:
& nbsp؛ در سند ریشه مستندات بسته روایت. این نظر گرفته شده است برای جمع آوری هر گونه فایل توضیحات آزمون که در میان ماژول پایتون در درخت منبع خود را دارند. شما نیاز به لیست فایل های زیر بخشنامه toctree، نام سند خود بودن از الگوی <فضای نام> - (بدون پسوند کلیپ برد چند منظوره). لیست عنوان مثال فایل اظهار نظر کردن گنجانده شده است.
توضیحات / 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 تولید نصب یک اسکریپت در بن / توضیحات که خواستار مجسمه ابوالهول برای ساختن مستندات. برای اجرای این اسکریپت، دایرکتوری جاری شما باید ریشه بسته باشد. اسکریپت مستندات ساخته شده را به ساخت / توضیحات / (نسبت به دایرکتوری سطح بالا بسته است) قرار داده است. گزینه های گذشت به بن / توضیحات خواهد شد در به زمینه ای دستور مجسمه ابوالهول ساخت به تصویب رسید، اما توجه داشته باشید که استدلال موضعی کار نخواهد کرد.
ارزش پیکربندی مجسمه ابوالهول
به طور پیش فرض، تعدادی از پسوند مجسمه ابوالهول فعال باشد، بنابراین شما ممکن است بخواهید برای پیکربندی این علاوه بر متغیرهای هسته مجسمه ابوالهول:
- 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'، 'GTK')

مورد نیاز:

پایتون