tl.pkg

tl.pkg е шаблон за namespaced пакет Python с Сфинкс Docs.
Този пакет генерира основния файл и директория оформлението на Python пакети със Сфинкса документация и buildout развитие. Тя се състои от две части:
- Шаблон paste.script който създава шаблон за опаковка Python, която живее в едно ниво на пространство от имена, и
- Пайтън модул, който се използва за конфигуриране на Сфинкса, заедно с необходимите пакетни зависимости и някои ГНУ.
Пакетът работи с Python 2.6 и 2.7.
<Силен> Usage
За да се направи шаблон Paster разположение, инсталиране tl.pkg където Paster мога да го намеря. След това стартирайте Paster:
& Nbsp;. Paster създаде --template TL-PKG <пространство от имена>
Това ще генерира шаблон за разпределение на едно яйце, пълно с zc.buildout конфигурация, скелета на Сфинкса комплект документи, и по-Mercurial хранилище инициализира. Конфигурацията на buildout е насочена към развитие, така че ще се инсталира testrunner в хамбар / тест и строител документация в хамбар / док.
Няколко променливи ще имат възможността да, сред тях описание на една линия и няколко думи за пакета.
<Силен> Персонализация
Още три променливи, които Paster Ви пита се използват за персонализиране на пакет скелет той ще генерира. Тези променливи могат да имат стойности по подразбиране, които се четат от файл с име $ HOME / .tl-pkg.cfg ако такава съществува. Файлът трябва да следват INI-файл синтаксис, както се разбира от ConfigParser Пайтън и съдържа една точка (с произволно име засега), който определя някои от следните променливи:
Автор: Трите ви имена. Това ще се появи в мета данни и документацията на пакетите, както и в известията за авторското право на никакви Python файлове, генерирани.
Автор-мейл: Вашият е-мейл адрес. Това се появява както в метаданните и документация пакет.
bitbucket-име: Вашият bitbucket потребителското име. Това се използва за изграждане на различни URL адреси, принадлежащи на проекта. В момента се изхожда от това, че проектът е домакин на и всички URL адреси в пакет метаданни и документация точката за да присвоят страници на тази bitbucket проект.
Съдържание Пакетни
Това е, за да обясни целта на генерираните файлове и директории, както и съвети за това кои файлове да редактирате кога. Много файлове не трябва да се редактира на всички.
Дистрибуция Python
setup.py: Определението на пакетите и метаданни. Актуализиране на този файл най-малко всеки път, когато версията на пакета, зависимости, входни точки се променят.
<Пространство от имена>: изходния код дървото на този пакет. Не променяйте __init__.py файл на пакета именно пространство да не би други пакети в същото пространство от имена не могат да бъдат внесени.
Mercurial хранилище
.hg: The Mercurial хранилище вече инициализиран, когато е създаден пакета. Генерираните файлове все още не са извършени.
.hg / hgrc: Repository конфигурация, че към бъдещия URL адреса на пакета в някои Mercurial хостинг, ако има такива. Тя установява също така си Hg потребителското име.
.hgignore: файлове и директории да бъдат игнорирани от Mercurial. Това включва местна конфигурация и неща очаква да бъдат генерирани от buildout, документация изгражда или пакет за пресата. Той не включва файлове, генерирани от Python (като * .pyc), разпространение (* .egg-инфо), или други по-общи инструменти като редактор, които не са специфични за този проект. Тези модели трябва да са по подразбиране Mercurial игнорираните теми.
Развитие buildout
bootstrap.py: Създава сценария на бин / buildout. Пусни тази със същия Python интерпретатора, че buildout трябва да използвате. Няма нужда да се някога редактирате този файл.
buildout.cfg: A buildout конфигурация работи, който създава тест бегач и строител документация за пакета. Самата опаковка е включена като развиват яйцата и buildout е конфигуриран да използва само тушира ​​версии на други пакети. Редактирате, за да конфигурирате официалния buildout развитие на пакета, но постави местните персонализации в local.cfg. Версия pinnings отиват във версии / versions.cfg докато раздел версии на този файл трябва да отмените само pinnings на пакети, които са обявени за разработване на яйца по вписванията buildout същия този файл е.
local.cfg: Местните персонализация на конфигурацията на buildout, че не представляват интерес за други разработчици. Това се пренебрегва от Mercurial. Ако промените този файл, стартирайте бин / buildout -С local.cfg от този момент нататък. Въпреки, че това може да звучи тромаво на първо, запазване на не-местна конфигурация в buildout.cfg и под контрол на версиите е важно за използването случаи, като например тестване на пакета на сървъра непрекъсната интеграция.
версии / versions.cfg:
& Nbsp; Version прикова за всички пакети, използвани от buildout, които не са част от инструментариума Zope. Версията на tl.pkg който е необходим за изграждането на документацията е закован на същата версия, която е създадена файловете пакети. При подобряването tl.pkg късно, тази версия прикова трябва да се актуализира заедно с всички файлове, които са се променили в шаблона на пакетите между версиите. Редактиране на файла с пин версиите на всички яйца, изисквани от вашия пакет или си buildout.
версии / ZTK-версии-X.Y.Z.cfg:
& Nbsp; Фиксиран освобождаване на инструментариума Zope, включени в нашата версия pinnings. Поддържане на локално копие на това позволява изграждането на buildout без достъп до мрежата. Не редактирате този файл.
General комплект документи
Има редица на текстови файлове, за да се намери в директорията на пакета от първо ниво, които съдържат стандартни парчета от документацията и затова се очаква на това място и по конкретните им имена, и който трябва да бъде достъпен, независимо от Сфинкса. Тези файлове трябва да бъдат валидни преструктурирани текст, тъй като те се обработват от Сфинкса, когато изграждането на пълна документация, с изключение на текста на авторски права и лицензи, които са включени дословно.
README.txt: Преглед на пакета предназначение, съдържание и използване, което ще бъде част от своята страница PyPI и на страницата с Индекса на документацията е. Това трябва да се поддържа актуална с съдържанието на пакета по всяко време.
CHANGES.txt: Дневникът на промяна, която трябва да се актуализира с всяка промяна в пакета, които са от значение за потребителите на пакета. Форматът на файла се разбира от zest.releaser и текущата версия на него (т.е. "върха" версия в публичен Mercurial хранилище) ще се посочи от страницата PyPI и вградения пакет документация.
ABOUT.txt: някои насоки за пакета и неговите автори, като е-мейл адрес на последния и адресите на документацията на пакета, PyPI страницата, бр тракера и изходния код, както и текущия регистър. Предполага се, че документацията ще се публикува, както у PyPI и при ; трябва да сте сигурни, за да използвате правилните съответните URL адреси, определени за вашия проект.
COPYRIGHT.txt: Copyright информация за пакета: притежателя на авторските права, включително годините за авторското право и някои съвети за лиценза използва, който е публичен лиценз Zope, версия 2.1 по подразбиране. Редактиране на тази най-малко да се актуализират години.
License.txt: Копие от официалния текст на лиценза използва. Не променяйте тази, освен да го размени за друг лиценз.
Пълна документация, изграден с помощта на Сфинкса
док: Всичко, което е от значение само за Сфинкса-генерирано документация. Ние използваме най-наставка .txt за Сфинкс входни файлове. Докато редица конвенции съществува за съдържанието на директорията, док, нищо лошо няма да се случи на останалата част от пакета, ако го променят свободно; Просто се уверете, че тя остава валидна Сфинкс вход.
док / conf.py: конфигурация Сфинкс. По принцип всички конфигурационни стойности следват конвенции и затова са внесени от tl.pkg, така че трябва да се запази на вноса и позоваването на tl.pkg.sphinxconf непокътнати. Вие ще трябва да редактирате файла, ако искате да промените нещо за метаданни или появата на документацията само за този пакет. Актуализациите на конвенциите за Сфинкса-генерирано документация ще бъдат придобити чрез обновяване tl.pkg.
док / index.txt: на първа страница на документацията. Тя включва галерията пакет от README.txt файла най-високо ниво, както и таблица на съдържанието, сочещи към секциите на пълна документация. Те включват генерирана API документация, някои мета информация за пакета и дневника за промяна. Редактиране на файла, ако искате да добавите секции най-високо ниво, например.
док / narrative.txt:
& Nbsp; корен документ на документацията за разказ пакет. Това има за цел да събере всички док-тестови файлове, които се намират между модулите Python в изходния си дърво. Трябва да добавя файловете по Директивата за toctree, техните имена документ, като на схемата <пространство от имена> <ИменаПакета> -. (без .txt суфикс). A коментира-изложени например файл регистрация е включена.
док / api.txt: корен документ на генерираните API документация. The API е документирано полуавтоматично в които трябва да се изброят в този файл, под autosummary директивата, всички модули да бъдат документирани, което се случва автоматично от този момент нататък. A коментира-изложени например модул регистрация е включена.
док / overview.txt:
& Nbsp; A мъниче да включва файла най-високо ниво README.txt. Няма нужда да редактирате този файл.
док / about.txt: Meta информация за пакета, съчетаващ файлове най-високо ниво ABOUT.txt, COPYRIGHT.txt и License.txt. Вие не ще трябва да редактирате файла.
док / changes.txt:
& Nbsp; A мъниче да включват файл CHANGES.txt на най-високо ниво. Няма нужда да редактирате този файл.
док / requirements.pip:
& Nbsp; Листването на Python яйца (различни от самия Сфинкс) необходими за изграждане на документацията. Това е предвиден за изграждане на документация . Вие ще трябва да бъде в белия списък с тях, за да бъдат в състояние да използват конвенциите, прилагани от 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: Ако е посочено, това се приема за адреса на flattr нещо за този проект и flattr бутони за дарения ще се появи в горната част на колоната от менюто на пълната документация. За да добавите бутон flattr към страницата PyPI, разкоментирате елемента "Подкрепа на проекта" в ABOUT.txt и попълнете адреса там.
_issuetracker_offline:
& Nbsp; Ако е истинска стойност, интеграцията bitbucket на интеграцията на sphinxcontrib-issuetracker ще бъде променен, така че няма да се опитате да влезете в сървъра при изграждане на документацията и Сфинкса план остава независим от достъп до мрежата. (Интеграция с други тракери не е взето грижи за този момент.) Това ще деактивира някои функции на интеграцията на тракера, но запази, например, способността за разширяване на issuetracker да признае обикновен текст издава номера.
И накрая, на модула tl.pkg.sphinxconf дефинира функция, която може да се обадите, за да се регистрирате макет модули, ако документацията е да бъде построен на система, като например , че не може да се инсталира определен код (като модули осъществява в С):
tl.pkg.sphinxconf.register_mock_modules ("Кайро", "gobject", "GTK")

<силни> Изисквания :

• Python