{
    "info": {
        "author": "Thomas Lotze",
        "author_email": "thomas@thomas-lotze.de",
        "bugtrack_url": null,
        "classifiers": [
            "Environment :: Plugins",
            "Framework :: Paste",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: Zope Public License",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2",
            "Programming Language :: Python :: 2.6",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 2 :: Only"
        ],
        "description": "====================================================================\ntl.pkg - A template for a namespaced Python package with Sphinx docs\n====================================================================\n\nThis package generates the basic file and directory layout of Python packages\nwith Sphinx documentation and a development buildout. It consists of two\nparts:\n\n- a `paste.script`_ template that creates the boilerplate for a Python package\n  that lives in one level of namespace, and\n\n- a Python module that is used to configure Sphinx, along with the necessary\n  package dependencies and some theming.\n\nThe package works with Python 2.6 and 2.7.\n\n.. _`paste.script`: http://pythonpaste.org/script/index.html\n\n\nUsage\n=====\n\nTo make the paster template available, install tl.pkg where paster can find\nit. Then run paster::\n\n    $ paster create --template tl-pkg <NAMESPACE>.<PROJECTNAME>\n\nThis will generate the boilerplate for an egg distribution, complete with\nzc.buildout configuration, the skeleton of Sphinx package documentation, and a\nMercurial repository initialised. The buildout configuration is targeted at\ndevelopment, so it will install a testrunner at ``bin/test`` and a\ndocumentation builder at ``bin/doc``.\n\nA few variables will be prompted for, among them a one-line description and\nsome keywords for the package.\n\nPersonalisation\n---------------\n\nThree more variables that paster asks you for are used to personalise the\npackage skeleton it will generate. These variables may have default values\nthat are read from a file named ``$HOME/.tl-pkg.cfg`` if it exists. The file\nneeds to follow ini-file syntax as understood by Python's ConfigParser and\ncontain one section (with an arbitrary name so far) that defines any of the\nfollowing variables:\n\n:author:\n    Your full name. This will appear in the package metadata and documentation\n    as well as in the copyright notices of any Python files generated.\n\n:author-email:\n    Your e-mail address. This appears both in the package metadata and\n    documentation.\n\n:bitbucket-name:\n    Your bitbucket user name. This is used to construct the various URLs\n    belonging to the project. At present, the assumption is that the project\n    is hosted at <http://bitbucket.org/> and any URLs in the package metadata\n    and documentation point to appropriate pages of that bitbucket project.\n\n\nPackage contents\n================\n\nThis is to explain the purpose of the generated files and directories, along\nwith advice on which files to edit when. Many files will not need to be edited\nat all.\n\nPython distribution\n-------------------\n\n:setup.py:\n    The package definition and metadata. Update this file at least whenever\n    the package's version number, dependencies, entry points change.\n\n:<NAMESPACE>:\n    The source code tree of the package. Don't modify the namespace package's\n    ``__init__.py`` file lest other packages in the same namespace cannot be\n    imported.\n\nMercurial repository\n--------------------\n\n:.hg:\n    The Mercurial repository is already initialised when the package has been\n    created. The generated files have not been committed yet.\n\n:.hg/hgrc:\n    Repository configuration that points to the future URL of the package in\n    some Mercurial hosting, if any. It also sets your hg user name.\n\n:.hgignore:\n    Files and directories to be ignored by Mercurial. This includes local\n    configuration and stuff expected to be generated by buildout,\n    documentation builds or package releases. It does not include files\n    generated by Python (such as ``*.pyc``), distribute (``*.egg-info``), or\n    other more general tools like your editor, which are not specific to this\n    project. Such patterns should be on your default Mercurial ignore list.\n\nDevelopment buildout\n--------------------\n\n:bootstrap.py:\n    Creates the ``bin/buildout`` script. Run this with the same Python\n    interpreter that buildout should use. No need to ever edit this file.\n\n:buildout.cfg:\n    A working buildout configuration that creates a test runner and a\n    documentation builder for the package. The package itself is included as a\n    develop egg and buildout is configured to use only pinned versions of any\n    other packages. Edit this to configure the package's official development\n    buildout but put local customisations in ``local.cfg``. Version pinnings\n    go in ``versions/versions.cfg`` while this file's versions section should\n    only undo pinnings of packages that are declared develop eggs by this same\n    file's buildout section.\n\n:local.cfg:\n    Local customisations of the buildout configuration that are of no interest\n    to other developers. This is being ignored by Mercurial. If you change\n    this file, run ``bin/buildout -c local.cfg`` from then on. While this may\n    sound cumbersome at first, keeping the non-local configuration in\n    ``buildout.cfg`` and under version control is important for use cases such\n    as testing the package on a continuous-integration server.\n\n:versions/versions.cfg:\n    Version pinning for any packages used by the buildout that are not part of\n    the Zope toolkit. The version of tl.pkg which is required for building the\n    documentation is pinned to the same version that created the package\n    files. When upgrading tl.pkg later, this version pinning needs to be\n    updated along with any files that have changed in the package template\n    between the versions. Edit this file to pin the versions of any eggs\n    required by your package or your buildout.\n\n:versions/ztk-versions-X.Y.Z.cfg:\n    A fixed release of the Zope toolkit, included in our version pinnings.\n    Keeping a local copy of this allows building the buildout without network\n    access. Do not edit this file.\n\nGeneral package documentation\n-----------------------------\n\nThere are a number of text files to be found in the package's top-level\ndirectory that contain standard pieces of the documentation and are therefore\nexpected in that place and under their particular names, and which need to be\naccessible independent of Sphinx. These files need to be valid restructured\ntext as they are being processed by Sphinx when building the full\ndocumentation, except for the copyright notice and licence text which are\nincluded verbatim.\n\n:README.txt:\n    An overview of the package's purpose, contents and usage which will be\n    part of its PyPI page and of the documentation's index page. This should\n    be kept up-to-date with the package contents at all times.\n\n:CHANGES.txt:\n    The change log that needs to be updated with any changes to the package\n    that are relevant to the users of the package. The file's format is\n    understood by ``zest.releaser`` and the current version of it (i.e. the\n    \"tip\" version in the public Mercurial repository) will be pointed to from\n    the PyPI page and the built package documentation.\n\n:ABOUT.txt:\n    Some pointers about the package and its authors, such as the latter's\n    e-mail address and the URLs of the package's documentation, PyPI page,\n    issue tracker and source code as well as the current log. It is assumed\n    that documentation will be be published both at PyPI and at\n    <http://readthedocs.org/>; you should make sure to use the correct\n    respective URLs assigned to your project.\n\n:COPYRIGHT.txt:\n    Copyright information for the package: copyright holder including the\n    copyright years and some advice about the licence used, which is the Zope\n    public licence, version 2.1 by default. Edit this at least to update the\n    years.\n\n:LICENSE.txt:\n    A copy of the official text of the licence used. Do not edit this except\n    to exchange it for a different licence.\n\nFull documentation, built using Sphinx\n--------------------------------------\n\n:doc:\n    Everything that is only relevant to the Sphinx-generated documentation. We\n    use the suffix ``.txt`` for Sphinx input files. While a number of\n    conventions exist for the contents of the ``doc`` directory, nothing bad\n    will happen to the rest of the package if you modify it freely; just make\n    sure it remains valid Sphinx input.\n\n:doc/conf.py:\n    Sphinx configuration. Basically all of the configuration values follow\n    conventions and are therefore imported from ``tl.pkg``, so you must keep\n    the import and invocation of ``tl.pkg.sphinxconf`` intact. You'll have to\n    edit this file if you want to change something about the metadata or the\n    appearance of the documentation just for this package. Updates to the\n    conventions for Sphinx-generated documentation will be acquired by\n    upgrading ``tl.pkg``.\n\n:doc/index.txt:\n    The front page of the documentation. It includes the package overview from\n    the top-level ``README.txt`` file and a table of contents pointing to the\n    sections of the full documentation. These include generated API\n    documentation, some meta information about the package and the change log.\n    Edit this file if you want to add top-level sections, for example.\n\n:doc/narrative.txt:\n    The root document of the narrative package documentation. This is intended\n    to collect any doc-test files that reside among the Python modules in your\n    source tree. You need to list the files under the ``toctree`` directive,\n    their document names being of the pattern\n    ``<NAMESPACE>.<PACKAGENAME>-<FILENAME>`` (without the ``.txt`` suffix). A\n    commented-out example file listing is included.\n\n:doc/api.txt:\n    The root document of the generated API documentation. The API is\n    documented semi-automatically in that you have to list in this file, under\n    the ``autosummary`` directive, all the modules to be documented, which\n    happens automatically from then on. A commented-out example module listing\n    is included.\n\n:doc/overview.txt:\n    A stub to include the top-level file ``README.txt``. No need to edit this\n    file.\n\n:doc/about.txt:\n    Meta information about the package, combining the top-level files\n    ``ABOUT.txt``, ``COPYRIGHT.txt``, and ``LICENSE.txt``. You will not need\n    to edit this file.\n\n:doc/changes.txt:\n    A stub to include the top-level file ``CHANGES.txt``. No need to edit this\n    file.\n\n:doc/requirements.pip:\n    A listing of Python eggs (other than Sphinx itself) required to build the\n    documentation. This is meant for building the documentation at\n    <http://readthedocs.org/>. You'll need to be whitelisted with them in\n    order to be able to use the conventions implemented by tl.pkg. Edit this\n    file whenever your documentation's package dependencies change; you cannot\n    use egg extras here.\n\n\nBuilding the full documentation\n===============================\n\nThe generated buildout configuration installs a script at ``bin/doc`` that\ncalls Sphinx to build the documentation. To run this script, your current\nworking directory must be the package root. The script will put the built\ndocumentation into ``build/doc/`` (relative to the package's top-level\ndirectory). Options passed to ``bin/doc`` will be passed on to the underlying\n``sphinx-build`` command, but note that positional arguments won't work.\n\n\nSphinx configuration values\n===========================\n\nBy default, a number of Sphinx extensions is enabled, so you might want to\nconfigure these in addition to the core Sphinx variables:\n\n- sphinx.ext.autosummary\n- sphinx.ext.viewcode\n- sphinx.ext.inheritance_diagram\n- sphinxcontrib.cheeseshop\n- sphinxcontrib.issuetracker\n\nYou can override the defaults from tl.pkg by simply setting the respective\nvariables in your conf.py. The invocation of\n``tl.pkg.sphinxconf.set_defaults`` needs to happen at the end::\n\n    source_suffix = '.foo'\n\n    import tl.pkg.sphinxconf\n    tl.pkg.sphinxconf.set_defaults()\n\nConversely, sphinxconf tries to use variables from ``conf.py`` to calculate\nvalues. If these variables are specified, that must also be done before\n``set_defaults`` is called. Currently, the following variables are recognised:\n\n:_year_started:\n    Optional value for the year the project was started. This defaults to the\n    current year (at the time of documentation building), but if it is\n    specified and different from the current year, it is used to construct a\n    copyright notice like \"2001-2012 Author\".\n\n:_flattr_url:\n    If specified, this is assumed to be the URL of a `flattr`_ thing for this\n    project and flattr donation buttons will appear at the top of the menu\n    column of the full documentation. To add a flattr button to the PyPI page,\n    uncomment the \"Support the project\" item in ``ABOUT.txt`` and fill in the\n    URL there as well.\n\n    .. _`flattr`: https://flattr.com/\n\n:_issuetracker_offline:\n    If set to a true value, the bitbucket integration of the\n    sphinxcontrib-issuetracker integration will be modified so that it won't\n    try to access the <http://bitbucket.org/> server when building the\n    documentation and the Sphinx run remains independent of network access.\n    (Integration with other trackers hasn't been taken care of so far.) This\n    will disable some functionality of the tracker integration but retain,\n    e.g., the issuetracker extension's ability to recognise plain-text issue\n    numbers.\n\nFinally, the tl.pkg.sphinxconf module defines a function that you may call to\nregister mock modules if the documentation is to be built on a system such as\n<http://readthedocs.org/> that cannot install certain code (like modules\nimplemented in C)::\n\n    tl.pkg.sphinxconf.register_mock_modules('cairo', 'gobject', 'gtk')\n\n\nKnown issues\n============\n\nThere is a known issue with project names that contain underscores. Due to the\nway tl.pkg infers metadata such as the project and package name from the\npackage's egg info, names with underscores would by default get their\nunderscores replaced by dashes, breaking the documentation build. To use\nunderscores in your project's name, explicitly repeat the name in\n``conf.py``::\n\n    project = '<NAMESPACE>.<PACKAGE_NAME_WITH_UNDERSCORES>'\n\n    import tl.pkg.sphinxconf\n    tl.pkg.sphinxconf.set_defaults()\n\n\n.. Local Variables:\n.. mode: rst\n.. End:\n\n\n============\nAbout tl.pkg\n============\n\n:Author:\n    `Thomas Lotze <http://thomas-lotze.de/>`_ <thomas@thomas-lotze.de>\n\n:PyPI page:\n    http://pypi.python.org/pypi/tl.pkg/\n\n:Issue tracker:\n    https://bitbucket.org/tlotze/tl.pkg/issues/\n\n:Source code:\n    https://bitbucket.org/tlotze/tl.pkg/\n\n:Current change log:\n    https://bitbucket.org/tlotze/tl.pkg/raw/tip/CHANGES.txt\n\n:Support the project:\n   .. image:: http://api.flattr.com/button/flattr-badge-large.png\n       :alt: Flattr this\n       :target:\n          http://flattr.com/thing/528493/tl-pkg-A-template-for-a-namespaced-Python-package-with-Sphinx-docs\n\n.. Local Variables:\n.. mode: rst\n.. End:",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://bitbucket.org/tlotze/tl.pkg/",
        "keywords": "paste.script paster create template python package sphinx docs theme development buildout",
        "license": "ZPL 2.1",
        "maintainer": null,
        "maintainer_email": null,
        "name": "tl.pkg",
        "package_url": "https://pypi.org/project/tl.pkg/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/tl.pkg/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "https://bitbucket.org/tlotze/tl.pkg/"
        },
        "release_url": "https://pypi.org/project/tl.pkg/0.1/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "A paste.script template for a namespaced Python package and a Sphinx theme.",
        "version": "0.1"
    },
    "last_serial": 800759,
    "releases": {
        "0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "976a5947ed92c7a809c6dab31f50b6fd",
                    "sha256": "ef8301385707fa02c44327392693612c4996da3a43f22bb1d0010323a79a6cce"
                },
                "downloads": -1,
                "filename": "tl.pkg-0.1.tar.gz",
                "has_sig": true,
                "md5_digest": "976a5947ed92c7a809c6dab31f50b6fd",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 29233,
                "upload_time": "2012-03-05T23:37:52",
                "url": "https://files.pythonhosted.org/packages/32/e8/98feb94b7212226ee0566ce7abe4edfc81f05b195022c9df22a6f4f56733/tl.pkg-0.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "976a5947ed92c7a809c6dab31f50b6fd",
                "sha256": "ef8301385707fa02c44327392693612c4996da3a43f22bb1d0010323a79a6cce"
            },
            "downloads": -1,
            "filename": "tl.pkg-0.1.tar.gz",
            "has_sig": true,
            "md5_digest": "976a5947ed92c7a809c6dab31f50b6fd",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 29233,
            "upload_time": "2012-03-05T23:37:52",
            "url": "https://files.pythonhosted.org/packages/32/e8/98feb94b7212226ee0566ce7abe4edfc81f05b195022c9df22a6f4f56733/tl.pkg-0.1.tar.gz"
        }
    ]
}