tl.pkg

tl.pkg jest szablon dla przestrzeni nazw pakietu Python z docs Sphinx.
Pakiet ten generuje podstawowy układ plików i katalogów z pakietów Pythona dokumentacji Sphinx i buildout rozwoju. Składa się ona z dwóch części:
- Szablon paste.script który tworzy szablonowe dla pakietu Python, który mieszka w jednym poziomie nazw i
- Moduł Pythona, który jest używany do konfigurowania Sphinx, wraz z niezbędnymi zależnościami pakietów i niektórych theming.
Pakiet współpracuje z Python 2.6 i 2.7.
Zastosowanie
Aby szablon naklejka dostępna, zainstaluj tl.pkg gdzie naklejka może go znaleźć. Następnie uruchom pastowania:
. & Nbsp; naklejka stworzyć --template TL-pkg
To wygeneruje boilerplate o wydanie dystrybucji jaj, wraz z konfiguracją zc.buildout, szkielet Sphinx dokumentacji pakietów oraz repozytorium Mercurial zainicjowane. Konfiguracja buildout skierowany jest do rozwoju, a więc będzie zainstalować TestRunner na bin / badania i budowniczy dokumentacji w bin / doc.
Kilka zmiennych zostanie poproszony o, między innymi opis jednej linii, a niektóre słowa kluczowe dla pakietu.
Personalizacja
Trzy kolejne zmienne, że naklejka prosi o służą do personalizacji szkielet pakiet będzie generować. Zmienne te mogą mieć wartości domyślne, które są odczytywane z pliku o nazwie $ HOME / .tl-pkg.cfg jeśli istnieje. Plik musi opierać się składni ini-file, jak rozumiane przez Pythona ConfigParser i zawiera jedną część (z dowolną nazwą do tej pory), która wyznacza jedną z następujących zmiennych:
autor: Twoje imię i nazwisko. To pojawi się w metadanych pakietów i dokumentacji, jak również o prawach autorskich dowolnych plików Pythona generowanych.
autor-mail: Twój adres e-mail. Pojawia się zarówno w metadanych pakietów i dokumentacji.
bitbucket-name: Nazwa użytkownika bitbucket. Jest używany do konstruowania różnych adresów należących do projektu. Obecnie zakłada się, że projekt jest hostowany na i wszystkie adresy URL w punkcie metadanych pakietów i dokumentacji do odpowiednich stron tego projektu bitbucket.
Zawartość opakowania
Ma to na celu wyjaśnić cel wygenerowanych plików i katalogów, wraz z radą, na których pliki do edycji, kiedy. Wiele pliki nie będą musiały być edytowane w ogóle.
Dystrybucji Python
setup.py: definicji pakietu i metadanych. Aktualizacja tego pliku przynajmniej wówczas, gdy numer wersji pakietu, w zależności, punkty wejścia zmiany.
: drzewa kodu źródłowego pakietu. Nie należy modyfikować plik __init__.py danego pakietu obszaru nazw bo inne pakiety w tej samej przestrzeni nazw nie mogą być importowane.
Mercurial repozytorium
.hg: Mercurial repozytorium jest już zainicjowane, gdy pakiet został utworzony. Wygenerowane pliki nie zostały jeszcze zatwierdzone.
.hg / hgrc: Repozytorium konfiguracji, która zwraca uwagę na przyszły URL pakietu w pewnym Mercurial hosting, jeśli w ogóle. Określa ona również nazwę użytkownika Hg.
.hgignore: Pliki i katalogi, które mają być ignorowane przez Mercurial. Obejmuje lokalnej konfiguracji i rzeczy oczekuje się być generowane przez buildout, dokumentacja buduje lub wydania pakietów. To nie obejmuje plików generowanych przez Python (takich jak * .pyc), dystrybucję (* .egg-info), lub inne, bardziej ogólne narzędzia, takie jak edytor, które nie są specyficzne dla tego projektu. Takie wzorce powinny być na domyślny Mercurial listy ignorowanych.
Buildout Rozwoju
bootstrap.py: Tworzy skrypt bin / buildout. Uruchom to z samego interpretera Pythona buildout powinien wykorzystać, że. Nie ma potrzeby, aby kiedykolwiek edytować ten plik.
buildout.cfg: konfiguracja buildout pracy, który tworzy zawodnik testowy i budowniczy dokumentacji pakietu. Samo opakowanie jest włączone jako jajkiem opracowania i buildout jest skonfigurowany do korzystania tylko przypięte wersje innych pakietów. Edytuj tę skonfigurować oficjalne buildout rozwoju danego pakietu, ale umieścić dostosowywać w local.cfg lokalnych. Pinnings Wersja iść w wersjach / versions.cfg natomiast sekcja wersje tego pliku powinna cofnąć tylko pinnings pakietów, które są zadeklarowane rozwoju jaj według sekcji buildout tego samego pliku.
local.cfg: Lokalne z dostosowywać konfiguracji buildout które nie są interesujące dla innych deweloperów. To jest ignorowane przez Mercurial. Jeśli zmienić ten plik, uruchom bin / buildout -c local.cfg od tej pory. Chociaż może wydawać się uciążliwe na początku, utrzymując zakaz lokalnej konfiguracji w buildout.cfg i pod kontrolą wersji jest ważny dla przypadków użycia, takich jak testowanie pakietu na serwerze ciągłej integracji.
Wersje / versions.cfg:
& Nbsp; Wersja przypinanie żadnych pakietów używanych przez buildout, które nie są częścią zestawu narzędzi Zope. Która jest niezbędna do budowania dokumentacji wersja tl.pkg jest przypięty do tej samej wersji, który utworzył pakiety. Podczas aktualizacji tl.pkg później, ta wersja przypinanie musi być aktualizowany wraz z dowolnych plików, które uległy zmianie w szablonie pakietu między wersjami. Edytuj plik, aby przypiąć wersje żadnych jaj wymaganych przez pakietu lub swojej buildout.
Wersje / ZTK-wersje-X.Y.Z.cfg:
& Nbsp; stałe wydanie biblioteki Zope, w naszych pinnings wersji. Prowadzenie lokalnej kopii pozwala budować buildout bez dostępu do sieci. Nie należy zmieniać tego pliku.
Ogólne dokumentacji pakietu
Istnieje wiele plików tekstowych można znaleźć w katalogu najwyższego poziomu danego pakietu, który zawiera standardowe fragmenty dokumentacji i dlatego oczekuje się w tym miejscu i pod ich poszczególnych nazw, a które muszą być dostępne niezależnie od Sfinksa. Pliki te muszą być ważny tekst restrukturyzacji, ponieważ są przetwarzane przez Sphinx przy budowie pełną dokumentację, z wyjątkiem informacji o prawach autorskich i licencji tekstu, zawarte dosłownie.
README.txt: przegląd przeznaczenia, zawartości i użytkowania danego pakietu, który będzie częścią jego stronie PyPI i strony indeksu dokumentacji znajduje. To powinno być stale na bieżąco z zawartością opakowania w każdej chwili.
Zmiany.txt: Dziennik zmian, które muszą być na bieżąco z wszelkimi zmianami w pakiecie, które są istotne dla użytkowników pakietu. Format pliku nie jest rozumiany przez zest.releaser i obecnej wersji to (czyli "tip" wersji w publicznym repozytorium Mercurial) będzie wskazywał na stronie PyPI i dokumentacji powykonawczej pakietu.
ABOUT.txt: Niektóre wskaźniki dotyczące pakietu i jego autorów, takich jak tego ostatniego adresu e-mail i adresy URL dokumentacji pakietu, strony PyPI, śledzenia błędów i kodu źródłowego, jak i bieżącego dziennika. Zakłada się, że dokumenty będą publikowane zarówno w PyPI i w ; należy się upewnić, że używamy poprawnych adresów URL przypisanych do projektu.
COPYRIGHT.txt: Informacje o prawach autorskich dla pakietu: właściciela praw autorskich, w tym roku autorskich i porady dotyczącej licencji używany, który jest licencja publiczna Zope, w wersji 2.1 domyślnie. Edytuj tę co najmniej zaktualizować lata.
License.txt: kopia oficjalnego tekstu licencji używanego. Nie należy zmieniać tego dopuścić, aby wymienić je na innej licencji.
Pełna dokumentacja, zbudowany przy użyciu Sphinx
doc: Wszystko, co dotyczy tylko Sphinx generowanego dokumentacji. Używamy .txt sufiksu dla plików wejściowych Sphinx. Chociaż istnieje wiele konwencji dla zawartości katalogu doc, nic złego się stanie z resztą pakietu, jeśli zmienić go swobodnie; tylko upewnić się, że nadal obowiązuje wejście Sfinks.
doc / conf.py: Konfiguracja Sphinx. Zasadniczo wszystkie wartości konfiguracyjne wykonaj następujące konwencje i dlatego są importowane z tl.pkg, więc należy zachować import i wywołanie tl.pkg.sphinxconf nienaruszone. Musisz edytować ten plik, jeśli chcesz zmienić coś na temat metadanych lub wyglądu dokumentacji tylko dla tego pakietu. Aktualizacje konwencji dla Sphinx generowanego dokumentacji zostaną nabyte przez uaktualnienie tl.pkg.
doc / index.txt: przednia strona dokumentacji. Zawiera on przegląd pakietu z plik README.txt najwyższego poziomu i spis treści skierowane do sekcji pełnej dokumentacji. Są to wygenerowany dokumentacji API, niektóre meta informacji o pakiecie i dzienniku zmian. Edytuj plik, jeśli chcesz dodać sekcje najwyższego poziomu, na przykład.
doc / narrative.txt:
& Nbsp; dokumentem głównym dokumentacji pakietu narracji. Ten przeznaczony jest do zbierania żadnych plików doc-testów, które znajdują się wśród modułów Pythona w drzewie źródłowym. Musisz listę plików w ramach dyrektywy toctree, ich nazwy dokumentu jako wzorca -. (bez rozszerzenia .txt). Zakomentowanych aukcja Przykładowy plik jest wliczony w cenę.
doc / api.txt: Dokument główny wygenerowanym dokumentacji API. API jest udokumentowane półautomatycznie się, że trzeba wymienić w tym pliku, pod autosummary dyrektywy, wszystkie moduły powinny być udokumentowane, co dzieje się automatycznie od tego momentu. Zakomentowanych przykład moduł wpis został włączony.
doc / overview.txt:
& Nbsp; en zawierać plik na najwyższym poziomie README.txt. Nie ma potrzeby zmieniać tego pliku.
doc / about.txt: Meta informacje o pakiecie, łącząc pliki najwyższego poziomu ABOUT.txt, COPYRIGHT.txt i License.txt. Nie trzeba będzie edytować tego pliku.
doc / Zmiany.txt:
& Nbsp; en zawierać plik Zmiany.txt najwyższego poziomu. Nie ma potrzeby zmieniać tego pliku.
doc / requirements.pip:
& Nbsp; wykaz jaj Pythona (inne niż samego Sfinksa) niezbędnych do stworzenia dokumentacji. To jest przeznaczona na budowę dokumentację w . Musisz być z nimi w białej listy, aby móc korzystać z konwencji realizowanych przez tl.pkg. Edytuj plik, gdy zależności pakietów dokumentacji na zmiany; nie można użyć tutaj dodatki jaj.
Tworzenie pełnej dokumentacji
Konfiguracja generowane buildout instaluje skrypt na bin / doc, że nazywa Sphinx budować dokumentację. Aby uruchomić ten skrypt, bieżący katalog roboczy musi być główny pakiet. Skrypt umieścić dokumentacji powykonawczej do budowy / doc / (w stosunku do katalogu najwyższego poziomu danego pakietu). Opcje przekazane bin / doc będą przekazywane do leżącej polecenia Sfinks-build, ale należy pamiętać, że argumenty pozycyjne nie działają.
Wartości Konfiguracja Sphinx
Domyślnie liczba rozszerzeń Sphinx jest włączone, więc możesz skonfigurować to oprócz podstawowych Sphinx zmiennych:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Można zastąpić ustawienia fabryczne z tl.pkg, ustawiając odpowiednie zmienne w conf.py. Wywołanie tl.pkg.sphinxconf.set_defaults musi się zdarzyć na końcu:
source_suffix = ".foo"
Import tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Odwrotnie, sphinxconf próbuje użyć zmiennych z conf.py do obliczania wartości. Jeśli te zmienne są określone, które muszą być również wykonane przed set_defaults nazywa. Obecnie rozpoznawane są następujące zmienne:
_year_started: opcja wartość dla roku projekt został uruchomiony. Domyślnie jest to w bieżącym roku (w czasie budowy dokumentacji), ale jeśli jest określona i różni się od obecnego roku, jest ona wykorzystywana do budowy prawach autorskich jak "2001-2012 Autor".
_flattr_url: Jeśli określony, to zakłada się, że adres URL Flattr rzeczy dla tego projektu i Flattr przycisków dawstwa pojawi się w górnej części kolumny menu z pełną dokumentacją. Aby dodać przycisk Flattr do strony PyPI odkomentować "Wsparcie projektu" element ABOUT.txt i wypełnić URL również tam.
_issuetracker_offline:
& Nbsp; Jeśli ustawione na true, integracja bitbucket integracji sphinxcontrib-issuetracker zostanie zmodyfikowany tak, że nie będzie próbował uzyskać dostęp do serwera przy tworzeniu dokumentacji i przebieg Sphinx pozostaje niezależne od dostępu do sieci. (Integracja z innych trackerów nie zostało załatwione do tej pory). Spowoduje to wyłączenie niektórych funkcji w integracji tracker ale zachowują, np, możliwość rozszerzenia issuetracker o uznaniu numery emisji zwykłego tekstu.
W końcu, moduł tl.pkg.sphinxconf definiuje funkcję, że można zadzwonić do rejestracji modułów makiety, czy dokumentacja ma być zbudowany na systemie, takich jak , że nie można zainstalować pewnego kodu (jak moduły realizowane C):
tl.pkg.sphinxconf.register_mock_modules ("Kair", "gobject ',' gtk ')

Wymagania :

• Python