Metadata-Version: 1.0
Name: gocept.package
Version: 1.0.1
Summary: A paste.script template following gocept Python package conventions.
Home-page: https://projects.gocept.com/projects/gocept-package/
Author: Thomas Lotze <tl at gocept dot com> and Wolfgang Schnerring <ws at gocept dot com>
Author-email: mail@gocept.com
License: ZPL 2.1
Description: ==============
        gocept.package
        ==============
        
        This package generates Python packages following conventions used at `gocept`_.
        
        .. _`gocept`: http://gocept.com/
        
        .. contents:: :depth: 1
        
        It consists of two parts: a paster template that creates the boilerplate for a
        Python package, and a Python module that is used to configure Sphinx, along
        with the necessary package dependencies.
        
        The package works with Python versions 2.5 through 2.7.
        
        
        Usage
        =====
        
        To make the paster template available, install gocept.package where paster can
        find it. Then run paster::
        
            $ paster create --template gocept-package NAMESPACE.PROJECTNAME
        
        This will generate the boilerplate for an egg distribution, complete with
        zc.buildout configuration, the skeleton of Sphinx package documentation, and a
        Mercurial repository initialised. The buildout configuration is targeted at
        development, so it will install a testrunner at ``bin/test`` and a
        documentation builder at ``bin/doc``.
        
        
        Package contents
        ================
        
        This is to explain the purpose of the generated files and directories, along
        with advice on which files to edit when. Many files will not need to be edited
        at all.
        
        Python distribution
        -------------------
        
        :setup.py:
            The package definition and metadata. Update this file at least whenever
            the package's version number, dependencies, entry points change.
        
        :src:
            The source code tree of the package. Don't modify the namespace package's
            ``__init__.py`` file lest other packages in the same namespace cannot be
            imported.
        
        Mercurial repository
        --------------------
        
        :.hg:
            The Mercurial repository is already initialised when the package has been
            created. The generated files have not been committed yet.
        
        :.hg/hgrc:
            Repository configuration that points to the future URL of the package in
            gocept's public Mercurial hosting. Edit this (or use ``hg persona``) if
            you need to set a different author for this package than your default.
        
        :.hgignore:
            Files and directories to be ignored by Mercurial. This includes local
            configuration and stuff expected to be generated by buildout,
            documentation builds or package releases. It does not include files
            generated by Python (such as ``*.pyc``), distribute (``*.egg-info``), or
            other more general tools like your editor, which are not specific to this
            project. Such patterns should be on your default Mercurial ignore list.
        
        Development buildout
        --------------------
        
        :bootstrap.py:
            Creates the ``bin/buildout`` script. Run this with the same Python
            interpreter that buildout should use. No need to ever edit this file.
        
        :buildout.cfg:
            A working buildout configuration that creates a test runner and a
            documentation builder for the package. The package itself is included as a
            develop egg and buildout is configured to use only pinned versions of any
            other packages. Edit this to configure the package's official development
            buildout but put local customisations in ``local.cfg``. Version pinnings
            go in ``versions/versions.cfg`` while this file's versions section should
            only undo pinnings of packages that are declared develop eggs by this same
            file's buildout section.
        
        :local.cfg:
            Local customisations of the buildout configuration that are of no interest
            to other developers. This is being ignored by Mercurial. If you change
            this file, run ``bin/buildout -c local.cfg`` from then on. While this may
            sound cumbersome at first, keeping the non-local configuration in
            ``buildout.cfg`` and under version control is important for use cases such
            as testing the package on a continuous-integration server.
        
        :versions/versions.cfg:
            Version pinning for any packages used by the buildout that are not part of
            the Zope toolkit. The version of gocept.package which is required for
            building the documentation is pinned to the same version that created the
            package files. When upgrading gocept.package later, this version pinning
            needs to be updated along with any files that have changed in the package
            template between the versions. Edit this file to pin the versions of any
            eggs required by your package or your buildout.
        
        :versions/ztk-versions-X.Y.Z.cfg:
            A fixed release of the Zope toolkit, included in our version pinnings.
            Keeping a local copy of this allows building the buildout without network
            access. Do not edit this file.
        
        Miscellaneous
        -------------
        
        :.coveragerc:
            Configuration for `coverage.py`_.
        
        .. _`coverage.py`: http://pypi.python.org/pypi/coverage
        
        
        General package documentation
        -----------------------------
        
        There are a number of text files to be found in the package's top-level
        directory that contain standard pieces of the documentation and are therefore
        expected in that place and under their particular names, and which need to be
        accessible independent of Sphinx. These files need to be valid restructured
        text as they are being processed by Sphinx when building the full
        documentation, except for the copyright notice and license text which are
        included verbatim.
        
        :README.txt:
            An overview of the package's purpose, contents and usage which will be
            part of its PyPI page and of the documentation's index page. This should
            be kept up-to-date with the package contents at all times.
        
        :CHANGES.txt:
            The change log that needs to be updated with any changes to the package
            that are relevant to the users of the package. The file's format is
            understood by ``zest.releaser`` and the current version of it (i.e. the
            "tip" version in the public Mercurial repository) will be pointed to from
            the PyPI page and the built package documentation.
        
        :HACKING.txt:
            Some pointers about the package and its authors, such as the latter's
            e-mail address and the URLs of the package's documentation, PyPI page,
            issue tracker and source code as well as the current log.
        
        :COPYRIGHT.txt:
            Copyright information for the package: copyright holder including the
            copyright years and some advice about the license used, which is the Zope
            public license, version 2.1 by default. Edit this at least to update the
            years.
        
        :LICENSE.txt:
            A copy of the official text of the license used. Do not edit this except
            to exchange it for a different license.
        
        Full documentation, built using Sphinx
        --------------------------------------
        
        :doc:
            Everything that is only relevant to the Sphinx-generated documentation. We
            use the suffix ``.txt`` for Sphinx input files. While a number of
            conventions exist for the contents of the ``doc`` directory, nothing bad
            will happen to the rest of the package if you modify it freely; just make
            sure it remains valid Sphinx input.
        
        :doc/conf.py:
            Sphinx configuration. Basically all of the configuration values follow our
            conventions and are therefore imported from ``gocept.package``, so you
            must keep the import and invocation of ``gocept.package.sphinxconf``
            intact. You'll have to edit this file if you want to change something
            about the metadata or the appearance of the documentation just for this
            package. Updates to our conventions for Sphinx-generated documentation
            will be acquired by updating ``gocept.package``.
        
        :doc/index.txt:
            The front page of the documentation. It includes the package overview from
            the top-level ``README.txt`` file and a table of contents pointing to the
            sections of the full documentation. These include generated API
            documentation, some meta information about the package and the change log.
            Edit this file if you want to add top-level sections such as a narrative
            package description.
        
        :doc/api.txt:
            The root document of the generated API documentation. The API is
            documented semi-automatically in that you have to list in this file, under
            the ``autosummary`` directive, all the modules to be documented, which
            happens automatically from then on. A commented-out example module listing
            is included.
        
        :doc/about.txt:
            Meta information about the package, combining the top-level files
            ``HACKING.txt``, ``COPYRIGHT.txt``, and ``LICENSE.txt``. You will not need
            to edit this file.
        
        :doc/changes.txt:
            A stub to include the top-level file ``CHANGES.txt``. No need to edit this
            file.
        
        
        Building the full documentation
        ===============================
        
        The generated buildout configuration installs a script at ``bin/doc`` that
        calls Sphinx to build the documentation. To run this script, your current
        working directory must be the package root. The script will put the built
        documentation into ``build/doc/`` (relative to the package's top-level
        directory). Options passed to ``bin/doc`` will be passed on to the underlying
        ``sphinx-build`` command, but note that positional arguments won't work.
        
        
        Sphinx configuration values
        ===========================
        
        You can override the defaults from gocept.package by simply setting the
        respective variables in your conf.py. The invocation of
        ``gocept.package.sphinxconf.set_defaults`` needs to happen at the end::
        
            source_suffix = '.foo'
        
            import gocept.package.sphinxconf
            gocept.package.sphinxconf.set_defaults()
        
        Conversely, sphinxconf tries to use variables from ``conf.py`` to calculate
        values. If these variables are specified, that must also be done before
        ``set_defaults`` is called. Currently, there is only one such variable:
        
        :_year_started:
            Optional value for the year the project was started. This defaults to the
            current year (at the time of documentation building), but if it is
            specified and different from the current year, it is used to construct a
            copyright notice like "2001-2012 Author".
        
        
        =========================
        Developing gocept.package
        =========================
        
        :Author:
            `gocept <http://gocept.com/>`_ <mail@gocept.com>
        
        :PyPI page:
            http://pypi.python.org/pypi/gocept.package/
        
        :Issue tracker:
            https://projects.gocept.com/projects/gocept-package/
        
        :Source code:
            https://code.gocept.com/hg/public/gocept.package/
        
        :Current change log:
            https://code.gocept.com/hg/public/gocept.package/raw-file/tip/CHANGES.txt
        
        
        =============================
        Change log for gocept.package
        =============================
        
        1.0.1 (2012-04-20)
        ==================
        
        - Add coveragerc to package skeleton.
        
        
        1.0 (2012-02-24)
        ================
        
        initial release
        
Keywords: paste.script paster create template python package sphinx theme
Platform: UNKNOWN
Classifier: Environment :: Plugins
Classifier: Framework :: Paste
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 2 :: Only
