Skip to content

Commit

Permalink
Merge commit 'fc89028e947f6babccdd3dffc1571b12fca75262' into base-on-…
Browse files Browse the repository at this point in the history 
…affiliate-template

Conflicts:
	.gitignore
	README.rst
	docs/conf.py
	setup.py
  • Loading branch information
@mwcraig
mwcraig committed Feb 25, 2014
2 parents 6ce8fb7 + fc89028 commit 9185b8b
Show file tree
Hide file tree
Showing 21 changed files with 974 additions and 23 deletions.
31 changes: 22 additions & 9 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,21 @@
*.py[cod]

# C extensions
# Compiled files
*.py[co]
*.a
*.o
*.so
__pycache__

# Ignore .c files by default to avoid including generated code. If you want to
# add a non-generated .c extension, use `git add -f filename.c`.
*.c

# Other generated files
*/version.py

# Sphinx
_build

# Packages
# Packages/installer info
*.egg
*.egg-info
dist
Expand All @@ -16,13 +28,14 @@ sdist
develop-eggs
.installed.cfg
lib
lib64
distribute-*.tar.gz

# Installer logs
pip-log.txt
# Other
.*.swp
*~

# Unit test / coverage reports
.coverage
# Mac OSX
.DS_Store
.tox
nosetests.xml

Expand Down
52 changes: 52 additions & 0 deletions .travis.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
language: python

python:
- 2.6
- 2.7
- 3.2
- 3.3

env:
# try all python versions with the latest stable numpy and astropy
- ASTROPY_VERSION=stable NUMPY_VERSION=1.7.1 SETUP_CMD='test'

matrix:
include:
- python: 2.7
# opdeps needed because the matplotlib sphinx extension requires them
env: ASTROPY_VERSION=development NUMPY_VERSION=1.7.1 SETUP_CMD='build_sphinx -w -n'

# try alternate numpy versions with the latest stable astropy
- python: 2.7
env: ASTROPY_VERSION=stable NUMPY_VERSION=1.6.2 SETUP_CMD='test'
- python: 2.7
env: ASTROPY_VERSION=stable NUMPY_VERSION=1.5.1 SETUP_CMD='test'
- python: 3.2
env: ASTROPY_VERSION=stable NUMPY_VERSION=1.6.2 SETUP_CMD='test'
# numpy < 1.6 does not work on py 3.x

# try latest developer version of astropy
- python: 2.7
env: ASTROPY_VERSION=development NUMPY_VERSION=1.7.1 SETUP_CMD='test'
- python: 3.3
env: ASTROPY_VERSION=development NUMPY_VERSION=1.7.1 SETUP_CMD='test'

before_install:
# We do this to make sure we get the dependencies so pip works below
- sudo apt-get update -qq
- sudo apt-get install -qq python-numpy python-sphinx cython libatlas-dev liblapack-dev gfortran
- if [[ $SETUP_CMD == build_sphinx* ]]; then sudo apt-get install -qq python-sphinx graphviz texlive-latex-extra dvipng python-matplotlib; fi

install:
- export PYTHONIOENCODING=UTF8 # just in case
- pip -q install --upgrade "numpy==$NUMPY_VERSION" --use-mirrors
- pip -q install --upgrade Cython --use-mirrors
- if [[ $SETUP_CMD == build_sphinx* ]]; then pip -q install sphinx==1.1.3 --use-mirrors; fi
- if [[ $SETUP_CMD == build_sphinx* ]]; then pip -q install matplotlib --use-mirrors; fi

- if [[ $ASTROPY_VERSION == stable ]]; then pip -q install astropy --use-mirrors; fi
- if [[ $ASTROPY_VERSION == development ]]; then pip -q install git+http://github.com/astropy/astropy.git#egg=astropy --use-mirrors; fi

script:
- python setup.py $SETUP_CMD

213 changes: 212 additions & 1 deletion README.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,216 @@
========================================
Scripts
=======

This directory contains command-line scripts for the affiliated package.
If you run into any problems, don't hesitate to ask for help on the
astropy-dev mailing list!

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

git clone git://github.com/astropy/package-template.git yourpkg

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"

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

git rm packagename/example_mod.py
git rm scripts/script_example
git rm packagename/example_c.pyx
git rm packagename/tests/test_example.py
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::

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

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"

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

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

git add README.rst
git commit -m "replaced README 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
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::

git remote rename origin template
git remote add upstream git@github.com:astropy/yourpkg.git

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

git push upstream master
git branch master --set-upstream upstream/master

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

git remote add origin git@github.com:yourgithubusername/yourpkg.git
git branch master --set-upstream origin/master

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 should register your package on https://travis-ci.org and modify the
``.travis.yml`` file to make the build pass. This will continuously test
your package for each commit, even pull requests against your main repository
will be automatically tested, so that you notice when something breaks.
For further information see
`here <https://github.com/astropy/astropy/wiki/Continuous-Integration>`_
and for lot's of example ``.travis.yml`` build configurations see
`here <https://github.com/astropy/astropy/wiki/travis-ci-test-status>`_.
Generally you should aim to always have your `master` branch work with
the latest stable as well as the latest development version of astropy
(i.e. the astropy git master branch).

* 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/
17 changes: 17 additions & 0 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,3 +113,20 @@
# (source start file, name, description, authors, manual section).
man_pages = [('index', project.lower(), project + u' Documentation',
[author], 1)]


## -- 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"
Loading

0 comments on commit 9185b8b

Please sign in to comment.