tl.pkg

tl.pkg шаблон для пространства имен пакета Python с Sphinx документы.
Этот пакет генерирует основную файла и каталога раскладки пакетов Python с Сфинкс документации и билдаута развития. Он состоит из двух частей:
- Шаблон paste.script, который создает макет для для пакета Python, который живет в одном уровне имен, и
- Модуль Питона, который используется для настройки Сфинкса, вместе с необходимыми зависимостями пакетов и какой-то тематизации.
Пакет работает с Python 2.6 и 2.7.
Использование
Для того, чтобы можно шаблон Пастер, установить tl.pkg где Пастер можете найти его. Затем запустите Пастер:
& NBSP;. Пастер создать --template TL-PKG <пространства имен>
Это создаст макет для для распределения яиц, в комплекте с конфигурацией zc.buildout, скелет пакета документации Сфинкса, и Mercurial репозитории, инициированную. Конфигурация Постройка ориентирована на развитие, так что это будет установить TestRunner на бен / теста и строитель документации на бен / Doc.
Несколько переменных будет предложено, среди них описание одной линии и некоторые ключевые слова для пакета.
Мой стиль
Еще три переменные, которые Пастер просит у вас используются, чтобы персонализировать пакет скелет будет генерировать. Эти переменные могут иметь значения по умолчанию, которые считываются из файла с именем $ HOME / .tl-pkg.cfg, если он существует. Файл должен следовать синтаксис INI-файл, как понятно, ConfigParser Python и содержит один раздел (с произвольным именем до сих пор), что определяет любой из следующих переменных:
Автор: Ваше полное имя. Эта надпись не появляется в метаданных пакета и документации, а также в уведомления об авторских правах любых файлов Python, генерируемых.
Автор электронная почта: Ваш адрес электронной почты. Это, кажется, как в метаданных пакета и документации.
Bitbucket имя: Ваш Bitbucket имя пользователя. Это используется для построения различных URL, принадлежащие к проекту. В настоящее время предполагается, что проект размещен на и любые URL-адреса в точке пакет метаданных и документации в соответствующие страницы этого Bitbucket проекта.
Содержание Package
Это должно объяснять цель сгенерированных файлов и каталогов, а также советы, на которых Файлы для редактирования когда. Многие файлы не должны быть отредактированы на всех.
Распределение Python
setup.py: Определение пакет и метаданные. Обновите этот файл, по крайней мере, когда номер версии пакета, в зависимости, изменять точки входа.
: Исходный код дерево пакета. Не изменяйте файл __init__.py пространство имен пакета в другие пакеты чтобы в то же пространство имен не могут быть импортированы.
Mercurial репозиторий
.hg: ртутный репозитория уже инициализирован, когда пакет был создан. Сформированные файлы еще не были совершены.
.hg / hgrc: хранилище конфигурации, который указывает на будущей URL пакета в какой-то Mercurial хостинг, если таковые имеются. Он также устанавливает свой рт.ст. имя пользователя.
.hgignore: Файлы и каталоги, которые будут игнорироваться Mercurial. Это включает в себя локальную конфигурацию и материал, как ожидается, порождается Постройка, документация строит или пакет релизы. Это не включает в себя файлы, созданные в Python (например, * .pyc), распространять (* .egg-данные), или другие более общие инструменты, такие как редактора, которые не специфичны для данного проекта. Такие модели должны быть на ваш список по умолчанию Mercurial игнорировать.
Постройка Разработка
bootstrap.py: Создает сценарий бен / Buildout. Запустите его с тем же переводчиком Python, что Постройка следует использовать. Нет необходимости когда-либо редактировать этот файл.
buildout.cfg: рабочая конфигурация Постройка, что создает тестовый бегун и строитель документации для пакета. Сам пакет входит в разработке яйца и Постройка настроен на использование только возлагали версии любых других пакетов. Редактировать настроить официальный Buildout развития пакета, но положил местных настройках в local.cfg. Версия pinnings перейти в версиях / versions.cfg в то время как версии раздел этот файл должен только отменить pinnings пакетов, которые объявлены развитию яйца от Buildout разделе эта же файла.
local.cfg: Местные настройках конфигурации Buildout, которые не представляют интереса для других разработчиков. Это игнорируются Mercurial. Если вы измените этот файл, запустите бен / Постройка -с local.cfg с тех пор. Хотя это может показаться громоздким сначала, сохраняя без локальной конфигурации в buildout.cfg и под контролем версий важно для использования таких случаях, как тестирование пакета на сервере непрерывной интеграции.
версии / versions.cfg:
& NBSP; Версия для закрепления любыми пакетами, используемых билдаута, которые не являются частью инструментария Zope. Версия tl.pkg который необходим для построения документации закреплен на той же версии, что созданный файлы пакета. При обновлении tl.pkg позже, эта версия возлагает потребности в обновлении наряду с любыми файлами, которые были изменены в шаблоне пакета между версиями. Редактировать этот файл, чтобы прикрепить версии любых яиц, необходимых пакета или вашего билдаута.
версии / ZTK-версии-X.Y.Z.cfg:
& NBSP; Фиксированный релиз инструментария Zope, включенные в нашей версии pinnings. Ведение локальную копию это позволяет строить Buildout без доступа к сети. Не изменяйте этот файл.
Общая документация пакет
Есть ряд текстовых файлов можно найти в каталоге верхнего уровня пакета в том, что содержат стандартные куски документации, и поэтому ожидается, в этом месте и под их конкретных имен, и который должен быть доступен независимо от Сфинкса. Эти файлы должны быть действительны реструктуризация текст, как они обрабатываются по Сфинкса при строительстве полную документацию, для уведомления об авторских правах и текст лицензии, которые включены дословно, за исключением.
README.txt: обзор предоставляемых пакетом назначения, содержания и использования, которые будут частью своей странице PyPi и главную страницу документации по. Это должно быть до современных с содержимым пакета на все времена.
Changes.txt: Журнал изменений, которые необходимо обновить с любыми изменениями в пакете, которые имеют отношение к пользователям пакета. Форматом файла понимается zest.releaser и текущей версией этого (т.е. «верхушка» версии в государственном хранилище Mercurial) будет направлен на на странице PyPi и встроенной пакета документации.
ABOUT.TXT: Некоторые указатели о пакете и его авторов, таких как адрес электронной почты последнего и URL-адресов в документации именования, PyPi странице, отслеживания проблем и исходного кода, а также текущий журнал. Предполагается, что документация будет опубликованы как на PyPI и в ; Вы должны убедиться, что использовать правильные соответствующие URL-адреса, назначенные в проект.
COPYRIGHT.txt: Информация об авторских правах для пакета: владельца авторских прав, включая авторских лет и несколько советов о используемой лицензии, которая является общественной лицензии Zope, версия 2.1 по умолчанию. Редактировать это по крайней мере, чтобы обновить годы.
LICENSE.TXT: Копия официального текста используемой лицензии. Не изменяйте это, за исключением обменять его на другой лицензией.
Полная документация, построен с использованием Sphinx
Doc: Все, что имеет отношение только к Сфинкс-генерации документации. Мы используем суффикс .txt для входных файлов Sphinx. В то время как ряд конвенций существуют для содержимого каталога DOC, ничего плохого не случится с остальной пакет, если вы измените его свободно; просто убедитесь, что она остается в силе входного Сфинкс.
DOC / conf.py: Конфигурация Сфинкс. В основном все значения конфигурации в соответствии с обычаями и поэтому импортируются из tl.pkg, так что вы должны держать на импорт и вызов tl.pkg.sphinxconf нетронутыми. Вы будете иметь, чтобы редактировать этот файл, если вы хотите что-то изменить в метаданных или появления документации только для этого пакета. Обновления конвенций для Сфинкс-генерации документации будут приобретены за счет модернизации tl.pkg.
DOC / index.txt: На первой странице документации. Она включает в себя обзор пакета из файла README.txt верхнего уровня и оглавления, указывающих на участках полной документации. Они включают в себя сгенерированный API документацию, некоторые мета-информацию о пакете и журнале изменений. Редактировать этот файл, если вы хотите, чтобы добавить разделы верхнего уровня, например.
DOC / narrative.txt:
& NBSP; Корень документ документации повествование пакета. Это предназначено для сбора любых док-тестовые файлы, которые находятся среди модулей Python в вашем исходном дереве. Вы должны перечислить файлы в соответствии с директивой toctree, их имена документов, являющихся рисунка -. <Имя файла> (без суффиксом .txt). Закомментированная список пример файла включены.
DOC / api.txt: Корень документ генерируемого API документации. В API документируется полуавтоматически, что вы должны перечислить в этом файле, под автореферата директивы, все модули должны быть документированы, что происходит автоматически с тех пор. Закомментированная список примеров модуль включен.
DOC / overview.txt:
& NBSP; заглушка включить файл верхнего уровня README.txt. Нет необходимости редактировать этот файл.
DOC / about.txt: Мета информация о пакете, сочетая файлы верхнего уровня ABOUT.TXT, COPYRIGHT.txt и LICENSE.TXT. Вам не нужно будет редактировать этот файл.
DOC / changes.txt:
& NBSP; заглушка включить файл changes.txt верхнего уровня. Нет необходимости редактировать этот файл.
DOC / requirements.pip:
& NBSP; Перечень Python яйца (кроме самого Сфинкса), необходимых для построения документации. Это предназначено для построения документации в . Вы должны быть в белом списке с ними для того, чтобы быть в состоянии использовать соглашения реализуемые tl.pkg. Редактировать этот файл, когда изменения зависимостей пакетов в документации по по; Вы не можете использовать яичные дополнительные услуги здесь.
Строительство полную документацию
Сформированный конфигурации Постройка устанавливает сценарий на бен / Doc, которая называет Сфинкса построить документацию. Чтобы запустить этот сценарий, ваш текущий рабочий каталог должен быть корневым пакет. Сценарий будет положить встроенную документацию на конструкции / DOC / (относительно каталога верхнего уровня программ пакета). Опции, передаваемые бен / DOC будет принят на команды, лежащей в основе сфинкса сборки, но обратите внимание, что позиционные аргументы не будут работать.
значения конфигурации Sphinx
По умолчанию, количество расширений Sphinx включена, так что вы, возможно, захотите настроить их в дополнение к основным Sphinx переменных:
- 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 будет изменена таким образом, что она не будет пытаться получить доступ к <> http://bitbucket.org/ сервер при построении документации и бег Sphinx остается независимым от доступа к сети. (Интеграция с другими трекерами не заботятся так далеко.) Это будет отключить некоторые функциональные возможности интеграции трекера, но сохранить, например, способность внутреннего абонента issuetracker распознавать простые текстовые число выпуск.
Наконец, модуль tl.pkg.sphinxconf определяет функцию, которая Вы можете позвонить зарегистрироваться макет модулей, если документация будет построен на системе, таких как , которые не могут установить определенный код (как модулей реализованы в C):
tl.pkg.sphinxconf.register_mock_modules ("Каир", "GObject ',' GTK ')

Требования

• Python