tl.pkg

tl.pkg is een sjabloon voor een naamruimten Python pakket met Sphinx docs.
Dit pakket levert de basis van bestanden en directory lay-out van Python pakketten met Sphinx documentatie en een ontwikkeling buildout. Het bestaat uit twee delen:
- Een paste.script sjabloon dat de standaardtekst voor een Python pakket dat woont in een niveau van namespace creëert, en
- Een Python module die wordt gebruikt voor Sphinx configureren samen met de nodige pakket afhankelijkheden en sommige theming.
Het pakket werkt met Python 2.6 en 2.7.
Gebruik
Om de paster sjabloon beschikbaar te stellen, installeer tl.pkg waar paster het kan vinden. Dan lopen paster:
& Nbsp;. Paster creëren --template tl-pkg
Dit zal de standaardtekst voor een ei distributie, compleet met zc.buildout configuratie, het skelet van Sphinx pakket documentatie, en een Mercurial repository geïnitialiseerd genereren. De buildout configuratie is gericht op de ontwikkeling, dus het kan een TestRunner bij bin / test en een documentatie bouwer op bin / doc zal installeren.
Een aantal variabelen wordt gevraagd om, onder hen een beschrijving op één lijn en enkele sleutelwoorden voor het pakket.
Persoonlijk
Drie variabelen die paster je gevraagd worden gebruikt om het pakket skelet zal genereren personaliseren. Deze variabelen kunnen hebben standaardwaarden die worden gelezen uit een bestand met de naam $ HOME / .tl-pkg.cfg als het bestaat. Het bestand moet ini-bestand syntax volgen begrijpen Python ConfigParser en een deel (met een willekeurige naam so far) bevatten dat een van de volgende variabelen gedefinieerd:
auteur: Uw volledige naam. Deze zal verschijnen in het pakket metadata en documentatie, evenals in het auteursrecht mededelingen van elke Python-bestanden gegenereerd.
auteur-mail: Uw e-mail adres. Dit blijkt zowel uit de verpakking metadata en documentatie.
BitBucket-naam: Uw BitBucket gebruikersnaam. Dit wordt gebruikt om de verschillende URL's die behoren tot het project construeren. Op dit moment is de veronderstelling is dat het project wordt gehost op en alle URL's in het pakket metadata en documentatie punt om pagina's van die BitBucket project toe te eigenen.
Inhoud Package
Dit is het doel van de gegenereerde bestanden en mappen leggen, samen met advies over welke bestanden te bewerken wanneer. Veel bestanden niet hoeft te worden bewerkt op alle.
Python distributie
setup.py: Het pakket definitie en metadata. Wijzig dit bestand tenminste wanneer het pakket versienummer, afhankelijkheden, ingangspunten veranderen.
: De broncode boom van het pakket. Laat __init__.py dossier van de namespace pakket niet wijzigen opdat andere pakketten in dezelfde namespace niet kunnen worden geïmporteerd.
Mercurial repository
.hg: De Mercurial repository is al geïnitialiseerd wanneer het pakket is gemaakt. De gegenereerde bestanden zijn nog niet begaan.
.hg / hgrc: Repository configuratie die wijst naar de toekomst URL van het pakket in sommige Mercurial hosting, indien van toepassing. Het zet ook uw hg gebruikersnaam.
.hgignore: Bestanden en mappen moeten worden genegeerd door Mercurial. Dit geldt ook voor lokale configuratie en spullen naar verwachting worden gegenereerd door buildout, documentatie bouwt of pakket releases. Het maakt niet bestanden die door Python (zoals * .pyc) omvatten, te distribueren (* .egg-info), of andere, meer algemene tools zoals je editor, die niet specifiek voor dit project zijn. Dergelijke patronen moet worden op uw standaard Mercurial negeer lijst.
Ontwikkeling buildout
bootstrap.py: Creëert de bin / buildout script. Voer dit met dezelfde Python-interpreter dat buildout moet gebruiken. Geen behoefte om ooit dit bestand te bewerken.
buildout.cfg: Een werkende buildout configuratie die een test loper en een documentatie bouwer voor het pakket creëert. Het pakket zelf is opgenomen als een ontwikkeling van ei en buildout is geconfigureerd om alleen speldde versies van andere pakketten te gebruiken. Pas aan officiële ontwikkelingshulp buildout het pakket te configureren maar zet lokale aanpassingen in local.cfg. Versie pinnings gaan versies / versions.cfg terwijl versies sectie van dit bestand moeten alleen ongedaan pinnings van pakketten die worden gedeclareerd ontwikkelen eieren door buildout sectie dit zelfde bestand.
local.cfg: Lokale aanpassingen van de buildout configuratie die niet van belang zijn voor andere ontwikkelaars. Dit wordt genegeerd door Mercurial. Als u dit bestand te wijzigen, voert bin / buildout -c local.cfg vanaf dat moment. Hoewel dit klinkt misschien omslachtig op het eerste, het houden van de niet-lokale configuratie in buildout.cfg en onder versiebeheer is belangrijk voor use cases zoals het testen van het pakket op een continue-integratie-server.
uitvoeringen / versions.cfg:
& Nbsp; versie pinning voor alle pakketten die door de buildout die geen deel uitmaken van de Zope toolkit. De versie van tl.pkg die nodig is voor de bouw van de documentatie wordt vastgemaakt aan dezelfde versie die het pakket bestanden aangemaakt. Bij het upgraden tl.pkg later, deze versie pinning moet worden samen met alle bestanden die zijn gewijzigd in het pakket sjabloon tussen de versies bijgewerkt. Bewerk dit bestand naar de versies van elke eieren vereist door uw pakket of uw buildout pin.
uitvoeringen / ZTK-versies-X.Y.Z.cfg:
& Nbsp; Een vaste release van de Zope toolkit, opgenomen in onze versie pinnings. Het bijhouden van een lokale kopie van deze staat de bouw van de buildout zonder toegang tot het netwerk. Dit bestand niet bewerken.
Algemeen pakket documentatie
Er zijn een aantal tekstbestanden te vinden in het pakket van de top-level directory die standaard stukken van de documentatie bevatten en wordt daarom verwacht dat in die plaats en onder hun specifieke namen, en die moeten toegankelijk zijn onafhankelijk van Sphinx zijn. Deze bestanden moeten geldig geherstructureerd tekst als ze worden verwerkt door Sphinx bij de bouw van de volledige documentatie, met uitzondering van de copyright en licentie-tekst die letterlijk zijn opgenomen zijn.
README.txt: Een overzicht van het pakket het doel, de inhoud en gebruik die een deel van haar PyPI pagina en van de documentatie van de indexpagina zal zijn. Dit moet up-to-date met de inhoud van het pakket te allen tijde worden gehouden.
CHANGES.txt: Het changelog die moet worden bijgewerkt met eventuele wijzigingen in het pakket dat aan de gebruikers van het pakket relevant zijn. Indeling van het bestand wordt begrepen door zest.releaser en de huidige versie van het (dwz de "tip" versie in de openbare Mercurial repository) wordt u doorverwezen naar de PyPI pagina en de gebouwde pakket documentatie.
ABOUT.txt: Enkele tips over het pakket en haar auteurs, zoals diens e-mailadres en de URL's van de documentatie van het pakket, PyPI pagina, issue tracker en broncode, evenals de huidige log. Aangenomen wordt dat de documentatie zal worden zowel op PyPI en op worden gepubliceerd; je moet ervoor zorgen om de juiste respectieve URL's toegewezen aan uw project te gebruiken.
Copyright.txt: Copyright informatie voor het pakket: auteursrechthebbende inbegrip van de auteursrechten jaren en wat advies over de gebruikte licentie, dat is de Zope Public License, versie 2.1 standaard. Bewerk deze ten minste tot het jaar te actualiseren.
LICENSE.txt: Een kopie van de officiële tekst van de licentie gebruikt. Niet bewerken dit, behalve om het te ruilen voor een andere licentie.
Volledige documentatie, gebouwd met behulp van Sphinx
doc: Alles dat is alleen relevant voor de Sphinx-gegenereerde documentatie. We gebruiken het achtervoegsel .txt voor Sphinx input-bestanden. Terwijl een aantal conventies bestaan ​​voor de inhoud van de doc directory, zal niets ergs gebeuren met de rest van het pakket als u deze vrij te wijzigen; maar zorg ervoor dat geldig Sphinx ingang blijft.
doc / conf.py: Sphinx configuratie. In principe alle configuratie waarden conventies volgen en bijgevolg van tl.pkg geïmporteerd, dus je moet de import en aanroeping van tl.pkg.sphinxconf intact te houden. Je moet dit bestand te bewerken als je iets wilt weten over de metadata of het uiterlijk van de documentatie voor dit pakket te wijzigen. Updates voor de conventies voor Sphinx-gegenereerde documentatie zal worden overgenomen door het upgraden tl.pkg.
doc / index.txt: De voorpagina van de documentatie. Het omvat het pakket overzicht van de README.txt top-level en een inhoudsopgave wijst naar de secties van de volledige documentatie. Deze omvatten gegenereerd API-documentatie, een aantal meta-informatie over het pakket en de change log. Bewerk dit bestand als u wilt top-level secties toe te voegen, bijvoorbeeld.
doc / narrative.txt:
& Nbsp; De wortel document van het verhaal pakket documentatie. Dit is bedoeld om eventuele doc-testbestanden die onder de Python modules in je source tree wonen verzamelen. Je nodig hebt om de bestanden weer onder de richtlijn toctree, hun document namen zijn van het patroon -. (zonder de .txt suffix). Een commentaar-out voorbeeld bestand lijst is opgenomen.
doc / api.txt: De wortel document van de gegenereerde API-documentatie. De API is semi-automatisch in dat je in deze file, onder de autosummary richtlijn, alle modules worden gedocumenteerd, dat automatisch gebeurt vanaf dan gedocumenteerd. Een commentaar-out voorbeeld module lijst is opgenomen.
doc / overview.txt:
& Nbsp; Een beginnetje aan de top-level-bestand README.txt bevatten. Geen behoefte om dit bestand te bewerken.
doc / about.txt: Meta informatie over het pakket, het combineren van de top-level-bestanden ABOUT.txt, copyright.txt en LICENSE.txt. Je zal niet nodig om dit bestand te bewerken.
doc / changes.txt:
& Nbsp; Een beginnetje aan de top-level-bestand CHANGES.txt bevatten. Geen behoefte om dit bestand te bewerken.
doc / requirements.pip:
& Nbsp; Een lijst van Python eieren (met uitzondering van Sphinx zelf) die nodig is om de documentatie te bouwen. Dit is bedoeld voor de bouw van de documentatie op . Je nodig hebt om de whitelist met hen om te kunnen de door tl.pkg conventies gebruiken. Dit bestand wanneer uw documentatie pakket afhankelijkheden veranderen; kun je ei extra's hier niet gebruiken.
Het bouwen van de volledige documentatie
De gegenereerde buildout configuratie installeert een script op bin / doc dat Sphinx oproepen om de documentatie te bouwen. Om dit script wilt uitvoeren, moet uw huidige werkmap het pakket wortel. Het script zal de ingebouwde documentatie in build / doc / (ten opzichte van het pakket top-level directory) te zetten. Opties doorgegeven aan bin / doc zal worden doorgegeven aan de onderliggende sfinx-build opdracht, maar let op dat positionele argumenten niet zal werken.
Sphinx configuratie waarden
Standaard wordt een aantal Sphinx extensies ingeschakeld, dus je zou willen om deze te configureren in aanvulling op de kern Sphinx variabelen:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
U kunt de standaardinstellingen van tl.pkg overschrijven door simpelweg het instellen van de respectieve variabelen in uw conf.py. De aanroeping van tl.pkg.sphinxconf.set_defaults moet gebeuren aan het eind:
source_suffix = '.foo'
import tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Omgekeerd sphinxconf probeert variabelen gebruiken van conf.py om waarden te berekenen. Indien deze variabelen worden gespecificeerd, die moet worden uitgevoerd voordat set_defaults genoemd. Momenteel worden de volgende variabelen opgenomen:
_year_started: Optioneel waarde voor het jaar waarin het project werd gestart. Dit is standaard ingesteld op het huidige jaar (op het moment van documentatie gebouw), maar als het is opgegeven en verschillend van het lopende jaar, het wordt gebruikt om een ​​copyright zoals "2001-2012 Auteur" te construeren.
_flattr_url: Als aangegeven, wordt aangenomen dat de URL van een Flattr ding voor dit project en Flattr donatie knoppen verschijnen aan de bovenkant van het menu kolom van de volledige documentatie. Om een ​​Flattr knop toe te voegen aan de PyPI pagina, uncomment de "Steun het project" object ABOUT.txt en in de URL te vullen daar ook.
_issuetracker_offline:
& Nbsp; Als er een werkelijke waarde, de BitBucket integratie van de sphinxcontrib-issuetracker integratie zal worden aangepast, zodat het niet zal proberen om toegang te krijgen tot de server bij de bouw van de documentatie en de Sfinx run blijft onafhankelijk van de toegang tot het netwerk. (Integratie met andere trackers heeft niet gezorgd is tot nu toe.) Dit zal sommige functies van de tracker integratie uit te schakelen, maar behouden, bijvoorbeeld, het vermogen van de issuetracker extensie om nummers platte tekst probleem herkennen.
Ten slotte is de tl.pkg.sphinxconf module definieert een functie die u kunt bellen om mock-modules te registreren als de documentatie zal worden gebouwd op een systeem zoals dat niet bepaalde code kan installeren (zoals modules geïmplementeerd in C):
tl.pkg.sphinxconf.register_mock_modules ('Cairo', 'gobject', 'gtk')

Eisen

• Python