tl.pkg

tl.pkg é um modelo para um pacote Python namespaced com docs Esfinge.
Este pacote gera o layout do arquivo e diretório básico de pacotes Python com documentação Sphinx e um buildout desenvolvimento. Ele consiste de duas partes:
- Um modelo paste.script que cria o clichê de um pacote Python que vive em um nível de namespace, e
- Um módulo Python que é usado para configurar Sphinx, junto com as dependências de pacotes necessários e alguns theming.
O pacote trabalha com Python 2.6 e 2.7.
Uso
Para tornar o modelo paster disponível, instale tl.pkg onde paster pode encontrá-lo. Em seguida, execute paster:
& Nbsp;. Paster criar --template tl-pkg
Isso irá gerar o clichê para uma distribuição de ovos, com configuração zc.buildout, o esqueleto de documentação do pacote Sphinx, e um repositório Mercurial inicializado. A configuração buildout é direcionado para o desenvolvimento, por isso vai instalar um TestRunner no bin / teste e um construtor de documentação no bin / doc.
Algumas variáveis ​​será requisitado, entre eles uma descrição de uma linha e algumas palavras-chave para o pacote.
Personalização
Mais três variáveis ​​que paster lhe pede são usadas para personalizar o esqueleto pacote que vai gerar. Essas variáveis ​​podem ter valores padrão que são lidos de um arquivo chamado $ HOME / .TL-pkg.cfg se ele existir. O arquivo deve seguir sintaxe ini-file como entendido por ConfigParser do Python e contém uma secção (com um nome arbitrário até agora) que define uma das seguintes variáveis:
autor: Seu nome completo. Isso vai aparecer nos metadados pacote e documentação, bem como nos avisos de direitos autorais de todos os arquivos gerados em Python.
autor-mail: Seu endereço de e-mail. Isto parece tanto nos metadados pacote e documentação.
bitbucket-name: Seu nome de usuário bitbucket. Isto é usado para construir as várias URLs pertencentes ao projecto. Actualmente, a suposição é de que o projeto está hospedado em e quaisquer URLs no ponto de metadados do pacote e documentação para páginas desse projeto bitbucket apropriar.
Conteúdo Pacote
Esta é para explicar o propósito dos arquivos e diretórios gerados, juntamente com conselhos sobre quais arquivos para editar quando. Muitos arquivos não precisará ser editado em tudo.
Distribuição Python
setup.py: A definição de pacote e metadados. Atualizar esse arquivo, pelo menos, sempre que o número da versão do pacote, dependências, pontos de entrada mudar.
: A árvore de código fonte do pacote. Não modifique arquivo __init__.py do pacote namespace para que outros pacotes no mesmo namespace não podem ser importados.
Repositório Mercurial
.hg: O repositório Mercurial já é inicializado quando o pacote foi criado. Os arquivos gerados não foram cometidos ainda.
.hg / hgrc: configuração Repository que aponta para o futuro URL do pacote em algum hosting Mercurial, se houver. Ele também define o seu nome de usuário hg.
hgignore: Arquivos e diretórios a serem ignorados por Mercurial. Isso inclui a configuração local e outras coisas deverão ser gerados por buildout, documentação constrói ou pacote releases. Ele não inclui arquivos gerados pelo Python (como * .pyc), distribuir (* .egg-info) ou outras ferramentas mais gerais, como o seu editor, que não são específicos para este projeto. Tais padrões devem estar na lista de seu padrão Mercurial ignorar.
Buildout Desenvolvimento
bootstrap.py: Cria o script bin / buildout. Executar este com o mesmo interpretador Python que buildout deve usar. Não há necessidade de sempre editar este arquivo.
buildout.cfg: A configuração buildout de trabalho que cria um corredor de teste e um construtor de documentação para o pacote. O pacote em si é incluído como um ovo de desenvolver e buildout está configurado para usar apenas versões fixadas de outros pacotes. Editar este configurar buildout desenvolvimento oficial do pacote, mas colocar personalizações locais em LOCAL.CFG. Pinnings Versão ir em versões / versions.cfg enquanto a seção versões deste ficheiro só deve desfazer pinnings de pacotes que são declaradas desenvolvem ovos por secção buildout este mesmo arquivo.
LOCAL.CFG: personalizações locais da configuração buildout que não são de interesse para outros desenvolvedores. Isso está sendo ignorado por Mercurial. Se você alterar esse arquivo, execute bin / buildout LOCAL.CFG -c partir de então. Enquanto isto pode parecer complicado no início, mantendo a configuração não-local em buildout.cfg e sob controle de versão é importante para casos de uso, tais como testar o pacote em um servidor de controle da integração.
versões / versions.cfg:
& Nbsp; Versão para fixar quaisquer pacotes utilizados pelo buildout que não fazem parte do kit de ferramentas Zope. A versão do tl.pkg que é necessário para construir a documentação está fixado para a mesma versão que criou os arquivos do pacote. Ao atualizar tl.pkg mais tarde, esta versão fixando precisa ser atualizado, juntamente com todos os arquivos que foram alterados no modelo de pacote entre as versões. Editar este arquivo para fixar as versões de todos os ovos necessários para o seu pacote ou seu buildout.
versões / ZTK-versions-X.Y.Z.cfg:
& Nbsp; A versão fixa do kit de ferramentas Zope, incluídos em nossos pinnings versão. Manter uma cópia local deste permite a construção do buildout sem acesso à rede. Não edite este arquivo.
Documentação geral pacote
Há uma série de arquivos de texto a ser encontrado no diretório de nível superior do pacote que contém peças padrão da documentação e, portanto, são esperados em que lugar, e sob os seus nomes específicos, e que precisam ser acessíveis independente da Esfinge. Esses arquivos precisam ser texto reestruturado válido como eles estão sendo processados ​​por Sphinx ao construir a documentação completa, exceto para o aviso de direitos autorais e de licença de texto que estão incluídos na íntegra.
README.txt: Uma visão geral de propósito, conteúdo e uso do pacote que será parte da sua página PyPI e da página de índice da documentação. Isto deve ser mantido up-to-date com o conteúdo do pacote em todos os momentos.
Changes.txt: O log de alterações que precisa ser atualizado com as mudanças para o pacote que são relevantes para os usuários do pacote. O formato do arquivo é entendida por zest.releaser ea versão atual do mesmo (ou seja, a versão de "ponta" no repositório Mercurial público) serão apontados a partir da página PyPI e a documentação do pacote construído.
About.txt: Algumas dicas sobre o pacote e os seus autores, tais como endereço de e-mail deste último e as URLs de documentação do pacote, PyPI página, issue tracker e código fonte, bem como o registro atual. Supõe-se que a documentação será ser publicado tanto no PyPI e em ; você deve certificar-se de usar os respectivos URLs corretas atribuídas ao seu projeto.
COPYRIGHT.txt: Informação de Copyright para o pacote: titular de direitos de autor, incluindo os anos de direitos autorais e alguns conselhos sobre a licença usada, que é a licença pública Zope, versão 2.1 por padrão. Editar este, pelo menos, para atualizar os anos.
LICENSE.txt: Uma cópia do texto oficial do certificado utilizado. Não edite isto exceto para trocá-lo por uma licença diferente.
A documentação completa, construída usando Sphinx
doc: Tudo o que só é relevante para a documentação Sphinx-gerado. Nós usamos o sufixo .txt para arquivos de entrada Esfinge. Enquanto existir uma série de convenções para o conteúdo do diretório doc, nada de ruim vai acontecer com o resto do pacote, se você modificá-lo livremente; apenas se certificar de que permanece entrada Sphinx válido.
doc / conf.py: configuração Sphinx. Basicamente todos os valores de configuração seguem as convenções e, portanto, são importados da tl.pkg, por isso você deve manter a importação e invocação de tl.pkg.sphinxconf intacta. Você vai ter que editar esse arquivo se você quer mudar alguma coisa sobre os metadados ou o aparecimento da documentação apenas para este pacote. Atualizações para as convenções para a documentação Sphinx gerado será adquirido por meio da atualização tl.pkg.
doc / index.txt: A primeira página da documentação. Ele inclui a visão geral do pacote do arquivo README.txt de nível superior e um índice apontando para as seções da documentação completa. Estes incluem a documentação da API gerada, algumas informações meta sobre o pacote e log de alterações. Editar este arquivo se você quiser adicionar seções de nível superior, por exemplo.
doc / narrative.txt:
& Nbsp; O documento raiz da documentação do pacote narrativa. Este destina-se a recolher todos os arquivos doc-teste que residem entre os módulos Python em sua árvore de origem. Você precisa listar os arquivos no âmbito da directiva toctree, seus nomes documento a ser do padrão -. (sem o sufixo .txt). Uma listagem exemplo arquivo comentou-out está incluído.
doc / api.txt: O documento raiz da documentação da API gerada. A API está documentado semi-automaticamente em que você tem a lista neste arquivo, ao abrigo da directiva AutoSummary, todos os módulos a ser documentado, o que acontece automaticamente a partir de então. Uma listagem exemplo módulo comentou-out está incluído.
doc / overview.txt:
& Nbsp; A stub para incluir o arquivo de nível superior README.txt. Não há necessidade de editar este arquivo.
doc / about.txt: Meta informações sobre o pacote, combinando os arquivos de nível superior about.txt, COPYRIGHT.txt e LICENSE.txt. Você não precisará editar esse arquivo.
doc / changes.txt:
& Nbsp; A stub para incluir o arquivo changes.txt de nível superior. Não há necessidade de editar este arquivo.
doc / requirements.pip:
& Nbsp; A listagem dos ovos Python (que não ele próprio Sphinx) necessários para construir a documentação. Este destina-se para a construção de documentação em . Você precisa estar na lista branca com eles, a fim de ser capaz de usar as convenções implementadas pelo tl.pkg. Editar este arquivo sempre que as dependências de pacotes da sua documentação mudar; você não pode usar extras de ovos aqui.
A construção da documentação completa
A configuração buildout gerado instala um script no bin / doc que chama Sphinx para construir a documentação. Para executar este script, o seu diretório de trabalho atual deve ser a raiz do pacote. O script vai colocar a documentação incorporada build / doc / (relativo ao diretório de nível superior do pacote). Opções passados ​​para bin / doc será repassado para o comando subjacente sphinx-build, mas note que argumentos posicionais não vai funcionar.
Valores de configuração esfinge
Por padrão, uma série de extensões Esfinge está habilitado, então você pode querer configurar estes para além das variáveis ​​esfinge centrais:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Você pode substituir os padrões de tl.pkg simplesmente definindo as respectivas variáveis ​​em sua conf.py. A invocação do tl.pkg.sphinxconf.set_defaults precisa acontecer no final:
source_suffix = '.foo'
tl.pkg.sphinxconf importação
tl.pkg.sphinxconf.set_defaults ()
Por outro lado, sphinxconf tenta usar variáveis ​​de conf.py para calcular valores. Se essas variáveis ​​são especificadas, que também deve ser feito antes set_defaults é chamado. Atualmente, as seguintes variáveis ​​são reconhecidas:
_year_started: valor opcional para o ano, o projeto foi iniciado. Esse padrão para o ano em curso (no momento da construção de documentação), mas se for especificado e diferente do ano em curso, ele é usado para a construção de um aviso de direitos autorais como "2001-2012 Autor".
_flattr_url: Se especificado, este é assumido como sendo o URL de uma coisa flattr para este projeto e botões de doação flattr aparecerá na parte superior da coluna de menu da documentação completa. Para adicionar um botão flattr à página PyPI, descomente a "apoiar o projeto" item no about.txt e preencha o URL lá também.
_issuetracker_offline:
& Nbsp; Se for definido como um valor verdadeiro, a integração bitbucket da integração sphinxcontrib-issuetracker será modificado para que ele não vai tentar acessar o servidor ao construir a documentação ea corrida Sphinx permanece independente de acesso à rede. (Integração com outros trackers não foi atendido até agora.) Isso irá desativar algumas funcionalidades da integração rastreador, mas manter, por exemplo, a capacidade da extensão issuetracker a reconhecer números de edição de texto sem formatação.
Por fim, o módulo tl.pkg.sphinxconf define uma função que você pode chamar para registrar os módulos de simulação, se a documentação está a ser construído em um sistema como que não é possível instalar determinado código (como módulos implementado em C):
tl.pkg.sphinxconf.register_mock_modules ('cairo', 'gobject', 'gtk')