-``update_copyright.py`` is an automatic copyright updating tool. I
-wrote the original for Bugs Everywhere, but ended up copying it into a
+``update-copyright`` is an automatic copyright updating tool. I wrote
+the original for `Bugs Everywhere`_, but ended up copying it into a
number of my projects. Copying is bad, so here it is, split out as
its own separate project.
+
+Installation
+============
+
+Packages
+--------
+
+Gentoo
+~~~~~~
+
+I've packaged ``update-copyright`` for Gentoo_. You need layman_ and
+my `wtk overlay`_. Install with::
+
+ # emerge -av app-portage/layman
+ # layman --add wtk
+ # emerge -av dev-util/update-copyright
+
+Dependencies
+------------
+
+``update-copyright`` is a simple package with few external
+dependencies. The only external dependencies are the Python packages
+behind Python-based version control systems. If you're using those
+VCSs, you've already installed the packages. If you're not using
+those VCSs, you don't need the packages.
+
+Installing by hand
+------------------
+
+``update-copyright`` is available as a Git_ repository::
+
+ $ git clone git://tremily.us/update-copyright.git
+
+See the homepage_ for details. To install the checkout, run the
+standard::
+
+ $ python setup.py install
+
+Usage
+=====
+
+You'll need a project that you version with one of our supported VCSs
+(currently Git, Mercurial, and Bazaar, but it should be pretty easy to
+add backends for other systems). You'll also need a config file
+called ``.update-copyright.conf`` in your package root, which will be
+parsed using Python's ConfigParser_ (`syntax documentation`_,
+interpolation is turned off). Your config file will look something
+like::
+
+ [project]
+ name: update-copyright
+ vcs: Git
+
+ [files]
+ authors: yes
+ files: yes
+ ignored: COPYING, README, .update-copyright.conf, .git*
+ pyfile: update_copyright/license.py
+
+ [copyright]
+ short: %(project)s comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU General Public License.
+ long: This file is part of %(project)s.
+
+ %(project)s is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+ %(project)s is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with %(project)s. If not, see <http://www.gnu.org/licenses/>.
+
+Options
+-------
+
+project/name
+ A string naming your project. Replaces ``%(project)s`` in your
+ copyright blurbs.
+project/vcs
+ The name of your version control system.
+files/authors
+ Should ``update-copyright.py`` generate an ``AUTHORS`` file?
+ ``yes`` or ``no``.
+files/files
+ Should ``update-copyright.py`` update copyright blurbs in versioned
+ files? ``yes`` or ``no``.
+files/ignored
+ A comma-separated list of globs matching files that should not have
+ copyright blurbs updated. This protects files that may accidentally
+ caught by the blurb update algorithm.
+files/pyfile
+ The path of an autogenerated license module, in case your program
+ wants to print out its copyright/licensing information. If you
+ don't set this option, no license module will be generated.
+copyright/short
+ A list of paragraphs (separated by blank lines) containing your
+ short copyright/license blurb. This blurb is used in the pyfile's
+ ``short_license`` function (see `files/pyfile`). This exists
+ because some programs print a short license blurb on startup, where
+ the full file-topping blurb may be overkill.
+copyright/long
+ A list of paragraphs (separated by blank lines) containing your long
+ copyright/license blurb. This blurb is used to replace copyright
+ blurbs in your source files.
+
+Updating copyright blurbs
+-------------------------
+
+The blurb-update algorithm looks for any lines that begin with ``#
+Copyright``. These lines mark the beginning of a blurb, which
+continues as long as subsequent lines begin with ``#``. The old blurb
+is replaced by a new blurb, which is automatically generated from your
+configured long copyright string, with author names and edit years
+extracted from the VCS data for that file.
+
+Testing
+=======
+
+Run the internal unit tests with::
+
+ $ nosetests --with-doctest --doctest-tests update_copyright
+
+Licence
+=======
+
+This project is distributed under the `GNU General Public License
+Version 3`_ or greater.
+
+Author
+======
+
+W. Trevor King
+wking@drexel.edu
+
+
+.. _Bugs Everywhere: http://bugseverywhere.org/
+.. _Gentoo: http://www.gentoo.org/
+.. _layman: http://layman.sourceforge.net/
+.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay
+.. _Git: http://git-scm.com/
+.. _homepage: http://blog.tremily.us/posts/update-copyright/
+.. _ConfigParser:
+ http://docs.python.org/dev/library/configparser.html#configparser.ConfigParser
+.. _syntax documentation:
+ http://docs.python.org/dev/library/configparser.html#supported-ini-file-structure
+.. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html
projects / update-copyright.git / commitdiff