Skip to content

Commit

Permalink
Simplify package-template usage and updating by requiring fewer files to
Browse files Browse the repository at this point in the history 
be edited.
  • Loading branch information
@mdboom
mdboom committed Mar 14, 2014
1 parent 857b7ae commit 0ca5ffe
Show file tree
Hide file tree
Showing 10 changed files with 271 additions and 281 deletions.
4 changes: 1 addition & 3 deletions MANIFEST.in
View file
Expand Up @@ -2,14 +2,12 @@ include README.rst

include ez_setup.py
include setuptools_bootstrap.py
recursive-include packagename *.pyx *.c

recursive-include docs *
recursive-include licenses *
recursive-include cextern *
recursive-include scripts *

exclude *.pyc *.o
exclude *.pyc *.o
prune docs/_build
prune build

159 changes: 48 additions & 111 deletions README.rst
View file
Expand Up @@ -30,57 +30,45 @@ will be clear from context what to do with your particular VCS.
This will download the latest version of the template from `github`_ and
place it in a directory named ``yourpkg``.

* Go into the directory you just created, and open the ``setup.py`` file
with your favorite text editor. Follow the steps below to update it for
your new package.

1. Change the ``PACKAGENAME`` variable to whatever you decide your package
should be named (for examples' sake, we will call it ``yourpkg``). By
tradition/very strong suggestion, python package names should be all
lower-case.
2. Change the ``DESCRIPTION`` variable to a short (one or few sentence)
description of your package.
3. Define a longer description as a string in the ``LONG_DESCRIPTION``
variable. You may want this to be the docstring of your package itself
as Astropy does. In this case, simply add ``import yourpkg`` somewhere
above, and set ``LONG_DESCRIPTION = yourpkg.__doc__``. Alternatively,
you may omit the description by deleting the variable and deleting the
line where it is used in the ``setup()`` function further down.
4. Add your name and email address by changing the ``AUTHOR`` and
``AUTHOR_EMAIL`` variables.
5. If your affiliated package has a website, change ``URL`` to point to that
site. Otherwise, you can leave it pointing to `Astropy`_ or just
delete it.
6. Exit out of your text editor

* Now tell git to remember the changes you just made::

git add setup.py
git commit -m "adjusted setup.py for new project yourpkg"

* Decide what license you want to use to release your source code. If you
don't care and/or are fine with the Astropy license, just edit the file
``licenses/LICENSE.rst`` with your name (or your collaboration's name) at
the top as the licensees. Otherwise, make sure to replace that file with
whatever license you prefer, and update the ``LICENSE`` variable in
``setup.py`` to reflect your choice of license. You also may need to
update the comment at the top of ``packagename/__init__.py`` to reflect your
choice of license. Again, tell git about your changes::

git add licenses/LICENSE.rst
git add setup.py # if you changed the license and modified setup.py
git commit -m "updated license for new project yourpkg"
* Go into the directory you just created, and open the ``setup.cfg``
file with your favorite text editor. Edit the settings in the
``affiliated`` section. These values will be used to automatically
replace special placeholders in the affiliated package template.

1. Change the ``package_name`` variable to whatever you decide your
package should be named. By tradition/very strong suggestion,
python package names should be all lower-case.
2. Change the ``description`` variable to a short (one or few
sentence) description of your package.
3. Add your name and email address by changing the ``author`` and
``author_email`` variables.
4. If your affiliated package has a website, change ``url`` to point
to that site. Otherwise, you can leave it pointing to `Astropy`_
or just delete it.
5. Exit out of your text editor

* Update the main package docstring in ``packagename/__init__.py``.

* Decide what license you want to use to release your source code. If
you don't care and/or are fine with the Astropy license, just edit
the file ``licenses/LICENSE.rst`` with your name (or your
collaboration's name) at the top as the licensees. Otherwise, make
sure to replace that file with whatever license you prefer, and
update the ``license`` variable in ``setup.cfg`` to reflect your
choice of license. You also may need to update the comment at the
top of ``packagename/__init__.py`` to reflect your choice of
license.

* Take a moment to look over the ``packagename/example_mod.py``,
``packagename/tests/test_example.py``, ``scripts/script_example``, and
``packagename/example_c.pyx`` files, as well as the
``packagename/tests/test_example.py``, ``scripts/script_example``,
and ``packagename/example_c.pyx`` files, as well as the
``packagename/example_subpkg`` directory. These are examples of a
pure-python module, a test script, an example command-line script, a
`Cython`_ module, and a sub-package, respectively. (`Cython`_ is a way to
compile python-like code to C to make it run faster - see the project's web
site for details). These are provided as examples of standard way to lay
these out. Once you understand these, though, you'll want to delete them
(and later replace with your own)::
`Cython`_ module, and a sub-package, respectively. (`Cython`_ is a
way to compile python-like code to C to make it run faster - see the
project's web site for details). These are provided as examples of
standard way to lay these out. Once you understand these, though,
you'll want to delete them (and later replace with your own)::

git rm packagename/example_mod.py
git rm scripts/script_example
Expand All @@ -89,82 +77,31 @@ will be clear from context what to do with your particular VCS.
git rm -r packagename/example_subpkg
git commit -m "removed examples from package template"

* Now rename the source code directory to match your project's name::

git mv packagename yourpkg
git commit -m "renamed template package source to new project yourpkg"

* Adjust the information in the documentation to match your new project by
editing the ``docs/conf.py`` file.

1. Change the ``project`` variable to your project's name (note that this
does not *need* to be exactly the same as the package name, but that's a
common convention).
2. Update the ``author`` variable with your name or the name of your collaboration.
3. Update the ``copyright`` variable for the current year.
4. Change the following lines::

import packagename
# The short X.Y version.
version = packagename.__version__.split('-', 1)[0]
# The full version, including alpha/beta/rc tags.
release = packagename.__version__

to::
* Optional: If you're hosting your source code on github, you can
enable a sphinx extension that will link documentation pages
directly to github's web site. To do this, set ``edit_on_github`` in
``setup.cfg`` to ``True`` and set ``github_project`` to the name of
your project on github.

import yourpkg
# The short X.Y version.
version = yourpkg.__version__.split('-', 1)[0]
# The full version, including alpha/beta/rc tags.
release = yourpkg.__version__
* Move the main source directory to reflect the name of your package.
To tell your DVCS about this move, you should use it, and not ``mv``
directly, to make the move. For example, with git::

where ``yourpkg`` is the name of your package.
5. (optional) If you're hosting your source code on github, you can
enable a sphinx extension that will link documentation pages
directly to github's web site. To do this, uncomment the code in
the "edit_on_github" section at the bottom of ``docs/conf.py``,
and replace ``packagename`` and ``reponame`` in that section with
the name of your package and github repository.


* Pass these changes on to git::

git add docs/conf.py
git commit -m "updated documentation for new project yourpkg"
git mv packagename yourpkg

* Update the names of the documentation files to match your package's name.
First open ``docs/index.rst`` in a text editor and change the text
``"packagename/index.rst"`` to e.g., ``"yourpkg/index.rst"``. Then do::

git add docs/index.rst
git mv docs/packagename docs/yourpkg
git commit -m "Updated docs to reflect new project yourpkg"

* (Optional) If you want integrated coverage testing, update the
coverage configuration. Open ``yourpkg/tests/coveragerc`` in a text
editor and change the ``source = packagename`` line to refer to the
name of your package. Any other project-specific settings for
``coverage.py`` can be added here. Open
``yourpkg/tests/setup_package.py`` and replace the package name
``packages.tests`` with ``yourpkg.tests``. Then do::

git add yourpkg/tests/coveragerc
git add yourpkg/tests/setup_package.py
git commit -m "Update coveragerc settings"

* Adjust the ``MANIFEST.in`` file to reflect your package's name by changing
the line 4 from ``recursive-include packagename *.pyx *.c`` to
``recursive-include yourpkg *.pyx *.c`` and pass this onto git::

... edit MANIFEST.in as described above...
git add MANIFEST.in
git commit -m "updated MANIFEST.in for new project yourpkg"

* Edit this file (``README.rst``) and delete all of this content, and replace it
with a short description of your affiliated package. Inform git::
with a short description of your affiliated package.

* Now tell git to remember the changes you just made::

git add README.rst
git commit -m "replaced README for new project yourpkg"
git commit -a -m "Adjusted for new project yourpkg"

* (This step assumes your affiliated package is hosted as part of the astropy
organization on Github. If it's instead hosted somewhere else, just adjust
Expand Down
52 changes: 31 additions & 21 deletions docs/conf.py
View file
Expand Up @@ -8,7 +8,7 @@
# Note that not all possible configuration values are present in this file.
#
# All configuration values have a default. Some values are defined in
# the global Astropy configuration which is loaded here before anything else.
# the global Astropy configuration which is loaded here before anything else.
# See astropy.sphinx.conf for which values are set there.

# If extensions (or modules to document with autodoc) are in another directory,
Expand All @@ -25,9 +25,17 @@
# Thus, any C-extensions that are needed to build the documentation will *not*
# be accessible, and the documentation will not build correctly.

import os
import sys

# Load all of the global Astropy configuration
from astropy.sphinx.conf import *

# Get configuration information from setup.cfg
from distutils import config
conf = config.ConfigParser()
conf.read([os.path.join(os.path.dirname(__file__), '..', 'setup.cfg')])
setup_cfg = dict(conf.items('affiliated'))

# -- General configuration ----------------------------------------------------

Expand All @@ -46,19 +54,22 @@
# -- Project information ------------------------------------------------------

# This does not *have* to match the package name, but typically does
project = u'Packagename'
author = u'The Packagename Developers'
copyright = u'2012, ' + author
project = setup_cfg['package_name']
author = setup_cfg['author']
copyright = '{0}, {1}'.format(
datetime.datetime.now().year, setup_cfg['author'])

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.

import packagename
__import__(setup_cfg['package_name'])
package = sys.modules[setup_cfg['package_name'])

# The short X.Y version.
version = packagename.__version__.split('-', 1)[0]
version = package.__version__.split('-', 1)[0]
# The full version, including alpha/beta/rc tags.
release = packagename.__version__
release = package.__version__


# -- Options for HTML output ---------------------------------------------------
Expand Down Expand Up @@ -116,17 +127,16 @@


## -- Options for the edit_on_github extension ----------------------------------------
#
#extensions += ['astropy.sphinx.ext.edit_on_github']
#
## Don't import the module as "version" or it will override the
## "version" configuration parameter
#from packagename import version as versionmod
#edit_on_github_project = "astropy/reponame"
#if versionmod.release:
# edit_on_github_branch = "v" + versionmod.version
#else:
# edit_on_github_branch = "master"
#
#edit_on_github_source_root = ""
#edit_on_github_doc_root = "docs"

if eval(setup_cfg.get('edit_on_github')):
extensions += ['astropy.sphinx.ext.edit_on_github']

versionmod = __import__(setup_cfg['package_name'] + '.version')
edit_on_github_project = setup_cfg['github_project']
if versionmod.release:
edit_on_github_branch = "v" + versionmod.version
else:
edit_on_github_branch = "master"

edit_on_github_source_root = ""
edit_on_github_doc_root = "docs"
15 changes: 7 additions & 8 deletions licenses/LICENSE.rst
View file
@@ -1,26 +1,25 @@
Copyright (c) 2011, Astropy Developers
Copyright (c) year, author
All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
* Neither the name of the Astropy Team nor the names of its contributors may be
used to endorse or promote products derived from this software without
* Neither the name of the Astropy Team nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

0 comments on commit 0ca5ffe

Please sign in to comment.