This package provides a template for packages that are affiliated with the

`Astropy`_ project. This package design mirrors the layout of the main

`Astropy`_ repository, as well as reusing much of the helper code used to

organize `Astropy`_. The instructions below describe how to take this

template and adjust it for your particular affiliated package.

Everywhere below that the text ``yourpkg`` is shown, replace it with the name

of your particular package.

**Note**: The instructions below assume you are using git for version control,

as is used by the Astropy repository. If this is not the case, hopefully it

will be clear from context what to do with your particular VCS.

* Make sure `Astropy`_ is installed, as the template depends in part on

Astropy to do its setup.

* You may have already done this if you are looking at this file locally, but

if not, you will need to obtain a copy of the package template. Assuming

you have `git`_ installed, just do::

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, simple 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::

* 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::

* 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/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)::

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

* 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. Change the following lines::

3. Update the ``copyright`` variable for the current year, and also your name

or the name of your collaboration (e.g.,"2011, John Doe and the

Amazing Package Collaboration.")

4. If you ever expect to output your docs in LaTeX or as a man page, you'll

also want to update the `latex_documents` and `man_pages` variables to

reflect your project, name, and author list.

* Pass these changes on to git::

* 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::

* 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 this file (``README.rst``) and delete all of this content, and replace it

with a short description of your affiliated package. Inform git::

* (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

the URL in the instructions below to match wherever your repository lives)

Now you will want to tell git that it should be pushing and pulling updates

to the repository of *your* project, rather than the package template::

Now that it is pointing to the correct master, you should push everything up

to your project and make sure that your local master is tied to your project

rather than the template. You'll only be able to do this if your github

repository is empty (if not, add the ``-f`` option to the ``push``

command - that will overwrite whatever is there)::

* (optional) If you are adopting the standard workflow used by `Astropy`_ with

github, you will also want to set up a fork of the repo on your own account,

by going to the Github page https://github.com/astropy/yourpkg and clicking

the "fork" button on the upper right. Then run the following commands::

Now you can push, pull, and branch whatever you want in your local fork

without affecting the official version, but when you want to push something

up to the main repository, just switch to the appropriate branch and do

``git push upstream master``.

* You're now ready to start doing actual work on your affiliated package. You

will probably want to read over the developer guidelines of the Astropy

documentation, and if you are hosting your code in GitHub, you might also

want to read the `Github help <http://help.github.com/>`_ to ensure you know

how to push your code to GitHub and some recommended workflows that work for

the core Astropy project.

* Once you have started work on the affiliated package, you should register

your package with the Astropy affiliated package registry. Instructions for

doing this will be provided on the `Astropy`_ website.

* Good luck with your code and your science!

.. _Astropy: http://www.astropy.org/

.. _git: http://git-scm.com/

.. _github: http://github.com

.. _Cython: http://cython.org/