GitLocker: The Coding Marketplace

Description:

gocept.package 3.1

gocept.package
This package generates Python packages following conventions used at gocept.

Contents

gocept.package
Developing gocept.package
Change log for gocept.package

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.7, 3.4, 3.5 and PyPy 2.

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.

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.rst:
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.rst:
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.rst:
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.rst 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.rst, 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.rst. 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 (HTML format) 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.
As an alternative to the default HTML output, bin/doc --pdf generates PDF
output in build/pdf (via Sphinx’ latex toolchain).

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 <mail@gocept.com>

PyPI page:
http://pypi.python.org/pypi/gocept.package/

Issues:
https://bitbucket.org/gocept/gocept.package/issues

Source code:
https://bitbucket.org/gocept/gocept.package/

Current change log:
https://bitbucket.org/gocept/gocept.package/raw/tip/CHANGES.rst

Run tests:
Use tox, for info see: https://pypi.python.org/pypi/tox

Change log for gocept.package

3.1 (2019-04-01)
Regression

This package is currently not compatible with Sphinx >= 1.7.

3.0 (2018-01-25)

Drop python 3.3 support as it is no longer supported by Sphinx 1.5.
Change License to MIT License.

2.3 (2016-12-02)

Ensure compatibility with setuptools > 30.0.

2.2 (2016-11-23)

Support PyPy 2.

2.1 (2016-02-19)

Use current bootstrap.py in the skeleton.

2.0 (2016-02-18)

Updated bitbucket URLs of current changelog files.
Drop support for Python 2.6.
Support Python 3.3, 3.4, 3.5.
Use tox as one and only testrunner.
Update to Sphinx >= 1.3.

1.3 (2014-09-17)

Add --pdf option to the bin/doc command.
Added a template for a minimal web-app deployment using batou.
Use py.test instead of zope.testrunner.

1.2 (2013-07-19)

Added .mr.developer.cfg to the skeleton’s .hgignore file.
Development buildout is now required to run in a Python environment that has
setuptools available.
Use zc.buildout 2.x and current setuptools instead of distribute in response
to the setuptools merge.
Updated package versions.

1.1 (2013-06-04)

Use pkginfo >= 0.9 which contains a fix for finding metadata of installed
namespace packages (see <https://bugs.launchpad.net/pkginfo/+bug/934311>).
Add example stanza for a console_script entrypoint to the skeleton setup.py.
Updated Mercurial links to point to bitbucket.org.
Updated link to online docs to point to pythonhosted.org.
Updated home page and issue reporting to remove outdated assumptions about
gocept’s project hosting.
Updated ZTK to 1.1.5, zc.buildout to 1.7.1.
Pin zc.buildout and distribute during bootstrap.

1.0.1 (2012-04-20)

Add coveragerc to package skeleton.

1.0 (2012-02-24)
initial release