tl.pkg

tl.pkg es una plantilla para un paquete Python namespaced con docs Esfinge.
Este paquete genera la disposición básica de archivos y directorios de paquetes de Python con la documentación esfinge y un buildout desarrollo. Se compone de dos partes:
- Una plantilla paste.script que crea el texto modelo para un paquete de Python que vive en un nivel de espacio de nombres, y
- Un módulo de Python que se utiliza para configurar Esfinge, junto con las dependencias de los paquetes necesarios y algunos theming.
El paquete trabaja con Python 2.6 y 2.7.
Uso
Para hacer la plantilla parche disponible, instale tl.pkg donde parche puede encontrarla. A continuación, ejecute parche:
& Nbsp;. Parche crear --template tl-pkg
Esto generará el texto modelo para una distribución de huevos, con configuración zc.buildout, el esqueleto de documentación del paquete Esfinge, y un repositorio Mercurial inicializado. La configuración buildout está dirigido a desarrollo, por lo que se instalará una TestRunner en bin / test y un constructor de documentación en bin / doc.
Se pedirá algunas variables, entre ellas una descripción de una línea y algunas palabras claves para el paquete.
Personalización
Tres variables más que parche por solicita se utilizan para personalizar el esqueleto paquete que va a generar. Estas variables pueden tener valores por defecto que se leen desde un archivo denominado $ HOME / .TL-pkg.cfg si existe. El archivo debe seguir la sintaxis ini-archivo tal como lo entiende ConfigParser de Python y contener una sección (con un nombre arbitrario hasta ahora) que define una de las siguientes variables:
autor: Su nombre completo. Esto aparecerá en los metadatos y documentación del paquete, así como en las notas de copyright de cualquier archivo de Python generados.
autor-mail: Tu dirección de correo electrónico. Esto aparece tanto en los metadatos y documentación del paquete.
bitbucket-name: El nombre de usuario bitbucket. Esto se utiliza para construir las diversas URLs pertenecientes al proyecto. En la actualidad, el supuesto es que el proyecto se hospeda en y cualquier URL en el punto paquete de metadatos y documentación para páginas de ese proyecto bitbucket apropiarse.
Contenidos Paquete
Esto es para explicar el propósito de los archivos generados y directorios, junto con consejos sobre qué archivos para editar cuando. No tendrán que ser editado en absoluto Muchos archivos.
Distribución Python
setup.py: La definición y metadatos del paquete. Actualizar este archivo al menos cada vez que el número de versión del paquete, las dependencias, los puntos de entrada cambian.
: El árbol de código fuente del paquete. No modifique archivo __init__.py del paquete de espacio de nombres por temor a otros paquetes en el mismo espacio de nombres no se pueden importar.
Repositorio Mercurial
.hg: El repositorio Mercurial ya ha sido inicializado cuando se ha creado el paquete. Los archivos generados no se han comprometido aún.
.hg / hgrc: configuración de repositorio que apunta al futuro URL del paquete de algún alojamiento Mercurial, en su caso. También establece el nombre de usuario hg.
.hgignore: Los archivos y directorios a ser ignorados por Mercurial. Esto incluye la configuración local y esas cosas se espera sean generados por buildout, documentación construye o versiones del paquete. No incluye los archivos generados por Python (como * .pyc), distribuir (* .egg-info), u otras herramientas más generales como su editor, que no son específicos de este proyecto. Estos patrones deben estar en la lista predeterminada Mercurial ignora.
Buildout Desarrollo
bootstrap.py: Crea el script bin / buildout. Ejecutar este con el mismo intérprete de Python que buildout debe utilizar. No hay necesidad de editar nunca este archivo.
buildout.cfg: Una configuración buildout de trabajo que crea un corredor de prueba y un constructor de la documentación del paquete. El propio envase se incluye como un huevo desarrollar y buildout está configurado para utilizar versiones sólo cubrió de cualquier otro paquete. Editar este para configurar buildout oficial para el desarrollo del paquete pero poner personalizaciones locales en LOCAL.CFG. Apuntalamientos Versión van en las versiones / versions.cfg mientras que la sección versiones de este archivo sólo debe deshacer apuntalamientos de paquetes que se declaran desarrollan los huevos por sección buildout de este mismo archivo.
LOCAL.CFG: personalizaciones locales de la configuración buildout que no son de interés para otros desarrolladores. Esto está siendo ignorada por Mercurial. Si cambia este archivo, ejecute bin / buildout LOCAL.CFG -c a partir de entonces. Si bien esto puede sonar complicado al principio, manteniendo la configuración no local en buildout.cfg y bajo control de versiones es importante para los casos de uso como prueba el paquete en un servidor continua integración.
versiones / versions.cfg:
& Nbsp; Versión fijando para los paquetes utilizados por el buildout que no forman parte del conjunto de herramientas Zope. La versión de tl.pkg que se requiere para la construcción de la documentación se fija en la misma versión que creó los archivos del paquete. Al actualizar tl.pkg después, esta versión fijando necesita ser actualizado, junto con todos los archivos que han cambiado en la plantilla de paquete entre las versiones. Editar este archivo de precisar las versiones de los huevos necesarios para su paquete o su buildout.
versiones / ZTK-versions-X.Y.Z.cfg:
& Nbsp; Una versión fija de la caja de herramientas de Zope, incluido en nuestra versión apuntalamientos. Mantener una copia local de este permite la construcción de la buildout sin acceso a la red. No edite este archivo.
Documentación general paquete
Hay una serie de archivos de texto que se encuentra en el directorio de nivel superior del paquete que contiene piezas estándar de la documentación y, por tanto, se espera que en ese lugar y bajo sus nombres particulares, y que tenga que ser independiente y accesible de la Esfinge. Estos archivos tienen que ser un texto reestructurado válida ya que están siendo procesados ​​por la Esfinge en la construcción de la documentación completa, a excepción de la nota de copyright y la licencia de texto que se incluyen textualmente.
README.txt: Una visión general de finalidad, contenido y uso del paquete que será parte de su página PyPI y de la página de índice de la documentación. Esto debe mantenerse al día con el contenido del paquete en todo momento.
CHANGES.txt: El registro de cambios que necesita ser actualizado con los cambios en el paquete que son relevantes para los usuarios del paquete. El formato del archivo es entendido por zest.releaser y la versión actual de la misma (es decir, la versión de "punta" en el repositorio Mercurial público) se señalará a la página PyPI y la documentación del paquete integrado.
ABOUT.txt: Algunos consejos sobre el paquete y sus autores, como el e-mail de este último y las direcciones URL de la documentación del paquete, página PyPI, seguimiento de incidencias y el código fuente, así como el registro actual. Se supone que la documentación se publicará tanto en PyPI y en ; usted debe asegurarse de utilizar las direcciones URL respectivas correctos asignados a su proyecto.
Copyright.txt: Información de copyright para el paquete: Titular de los derechos de autor incluyendo los años de derechos de autor y algunos consejos sobre la licencia utilizada, que es la licencia pública Zope, la versión 2.1 de forma predeterminada. Editar este al menos para actualizar los años.
LICENSE.txt: Una copia del texto oficial de la licencia usada. No editar esto excepto para cambiarlo por una licencia diferente.
La documentación completa, construida usando Esfinge
doc: Todo lo que sólo es relevante para la documentación generada por la Esfinge. Usamos el .txt sufijo para los archivos de entrada Esfinge. Si bien una serie de convenios existe para el contenido del directorio doc, nada malo va a pasar con el resto del paquete si lo modifica libremente; sólo asegúrese de que sigue siendo de entrada Esfinge válida.
doc / conf.py: configuración Esfinge. Básicamente todos los valores de configuración de seguir las convenciones y, por tanto, son importados de tl.pkg, por lo que debe mantener la importación y la invocación de tl.pkg.sphinxconf intacta. Vas a tener que editar este archivo si desea cambiar algo en los metadatos o la aparición de la documentación sólo para este paquete. Las actualizaciones de las convenciones de la documentación generada por el Esfinge serán adquiridas mediante la mejora de tl.pkg.
doc / index.txt: La primera página de la documentación. Incluye la descripción general del paquete del archivo README.txt de nivel superior y una tabla de contenidos que apuntan a las secciones de la documentación completa. Estos incluyen documentación de la API generado, algunos meta-información sobre el paquete y el registro de cambios. Editar este archivo si desea agregar secciones de nivel superior, por ejemplo.
doc / narrative.txt:
& Nbsp; El documento raíz del paquete de documentación narrativa. Con ello se pretende recopilar cualquier archivo doc-prueba que residen entre los módulos de Python en su árbol de fuentes. Es necesario enumerar los archivos bajo la directiva toctree, sus nombres de los documentos siendo del patrón -. (sin el sufijo .txt). Un listado ejemplo de archivo comentada está incluido.
doc / api.txt: El documento raíz de la documentación de la API generada. El API se documenta de forma semiautomática en que usted tiene que enumerar en este archivo, según la Directiva autosummary, todos los módulos a ser documentados, lo que ocurre de forma automática a partir de entonces. Un listado ejemplo módulo comentada está incluido.
doc / overview.txt:
& Nbsp; Un talón de incluir el archivo de nivel superior README.txt. No hay necesidad de editar este archivo.
doc / about.txt: Meta información sobre el paquete, que combina los archivos de nivel superior ABOUT.txt, copyright.txt y License.txt. Usted no tendrá que editar este archivo.
doc / changes.txt:
& Nbsp; Un talón para incluir el CHANGES.txt archivo de nivel superior. No hay necesidad de editar este archivo.
doc / requirements.pip:
& Nbsp; Una lista de los huevos de Python (que no sea la propia Esfinge) requerido para construir la documentación. Esto es para la construcción de la documentación a . Tendrá que estar en la lista blanca con ellos con el fin de poder utilizar las convenciones aplicadas por tl.pkg. Editar este archivo cada vez que las dependencias del paquete de su documentación cambian; no puede utilizar extras huevo aquí.
La construcción de la documentación completa
La configuración buildout generada instala un script en bin / doc que llama Esfinge para construir la documentación. Para ejecutar este script, el directorio de trabajo actual debe ser la raíz del paquete. El guión pondrá la documentación incorporada en construcción / doc / (en relación con el directorio de nivel superior del paquete). Opciones que se pasan a bin / doc serán pasados ​​al comando esfinge-construcción subyacente, pero tenga en cuenta que los argumentos posicionales no funcionarán.
Valores de configuración esfinge
Por defecto, una serie de extensiones Esfinge está activado, por lo que es posible que desee configurar estos, además de las variables fundamentales de la esfinge:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Puede anular los valores predeterminados de tl.pkg, simplemente definiendo las respectivas variables en su conf.py. La invocación de tl.pkg.sphinxconf.set_defaults tiene que ocurrir al final:
source_suffix = '.foo'
tl.pkg.sphinxconf importación
tl.pkg.sphinxconf.set_defaults ()
Por el contrario, sphinxconf trata de utilizar variables de conf.py para calcular los valores. Si se especifican estas variables, que también se debe hacer antes de set_defaults se llama. En la actualidad, se reconocen las siguientes variables:
_year_started: valor opcional para el año que se inició el proyecto. Por defecto es el año en curso (en el momento de la creación de la documentación), pero si se especifica y diferente del año en curso, que se utiliza para la construcción de un aviso de copyright como "Autor 2001-2012".
_flattr_url: Si se especifica, se asume que es la dirección URL de una cosa flattr para este proyecto y botones de donación Flattr aparecerá en la parte superior de la columna en el menú de la documentación completa. Para añadir un botón Flattr a la página PyPI, elimine el elemento "Apoyar el proyecto" en ABOUT.txt y rellenar el URL allí también.
_issuetracker_offline:
& Nbsp; Si se establece en un valor verdadero, la integración bitbucket de la integración sphinxcontrib-issuetracker se modificará para que no intentará acceder al servidor cuando la construcción de la documentación y la carrera Esfinge sigue siendo independiente de acceso a la red. (Integración con otros trackers no ha sido cuidado hasta el momento.) Esto desactivará algunas funciones de la integración rastreador pero conservan, por ejemplo, la capacidad de la extensión issuetracker reconocer números de incidencias de texto sin formato.
Por último, el módulo tl.pkg.sphinxconf define una función que puede llamar para registrar módulos simulados si la documentación se va a construir en un sistema como el que no se puede instalar cierto código (como módulos implementado en C):
tl.pkg.sphinxconf.register_mock_modules ('cairo', 'GObject', 'gtk')