Skip to content

Commit 6bf603c

Browse files
eteqkeflavich
authored andcommitted
updated docs Makefile to reflect astropy
Move the py.test conftest.py file to the astropy directory so it is installed. Changed the import of plugins accordingly. Also updated the .gitignore file so it ignores the Mac OS X .DS_Store file. fixed conf.py to not insert source dir into sys.path typo fixes in conf.py comment Added CSS file from Astropy core package Updated setup.cfg to match Astropy core package Copy bootstrap-astropy theme from astropy remove default.css import from astropy.css - now not needed update conf.py to use bootstrap-astropy theme, mirror astropy's version use installed astropy theme Added templates that inherit from core package Added `_templates` to list of patterns to exclude added comment directing to base of jinja template Update testing to only import pytest when tests are run Added `coverage` option that was added in the Astropy core Removed comments added kwarg options to test runner removed line setting unused _test_runner variable Updated setup.py to bring it in line with the Astropy core Update distribute_setup.py to 0.6.28 Remove unnecessary instructions from README.rst tweak to instructions from @astrofrog's suggestion Changed check in setup.py to syntax in core package to avoid issues when Sphinx is not installed. Update setup.py to reflect re-factored setup code for 0.2 release If necessary, move configuration file to the right place on first import Added open_files option for test() and implemented fix for caught exception in __init__.py Fix scripts/README.rst bug added commented-out edit_on_github section to conf.py and related instructions in README line wrap fixes Add .travis.yml file Add instructions for travis-ci to README _PACKAGE_SETUP_ should be _ASTROPY_SETUP_ (see astropy/astropy#950) Test with different Numpy versions, only test Sphinx with Python 2.7. Ensure that optional dependencies for Sphinx are installed Updated distribute_setup.py to fix compatibility with setuptools 0.7 README typo fixes Switch to using ez_setup.py, and simplify setup.py, following recent changes in Astropy core. Updates to __init__.py to match Astropy core Minor fix Added backward compatibility with Astropy 0.2 parallel option can only be used with Astropy 0.3 or later Re-organize the setup.py so that Astropy is not required for egg_info Revert "Re-organize the setup.py so that Astropy is not required for egg_info" This reverts commit 9aa533907f20f346b0cc55749224f6a15ff7e22a. Replace distribute_setup.py with ez_setup.py and ``setuptools_bootstrap.py`` Support `setup.py test --coverage` in affiliated packages. Simplify package-template usage and updating by requiring fewer files to be edited. Add information about pulling changes to package template Store stuff in "metadata" section, not "affiliated" section. Insert space before comment. Fix documentation build Elaborate on the need to search for .c files in a comment. Change ``clean`` rule to remove generated docs Made necessary by astropy/astropy@b94fd38 removed examples from package template setup configuration remove cextern
1 parent 58106d9 commit 6bf603c

26 files changed

Lines changed: 830 additions & 871 deletions

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ __pycache__
1111

1212
# Other generated files
1313
*/version.py
14+
htmlcov
15+
.coverage
1416

1517
# Sphinx
1618
_build
@@ -32,3 +34,6 @@ distribute-*.tar.gz
3234
# Other
3335
.*.swp
3436
*~
37+
38+
# Mac OSX
39+
.DS_Store

‎.travis.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
language: python
2+
3+
python:
4+
- 2.6
5+
- 2.7
6+
- 3.2
7+
- 3.3
8+
9+
env:
10+
# try all python versions with the latest stable numpy and astropy
11+
- ASTROPY_VERSION=stable NUMPY_VERSION=1.7.1 SETUP_CMD='test'
12+
13+
matrix:
14+
include:
15+
- python: 2.7
16+
# opdeps needed because the matplotlib sphinx extension requires them
17+
env: ASTROPY_VERSION=development NUMPY_VERSION=1.7.1 SETUP_CMD='build_sphinx -w -n'
18+
19+
# try alternate numpy versions with the latest stable astropy
20+
- python: 2.7
21+
env: ASTROPY_VERSION=stable NUMPY_VERSION=1.6.2 SETUP_CMD='test'
22+
- python: 2.7
23+
env: ASTROPY_VERSION=stable NUMPY_VERSION=1.5.1 SETUP_CMD='test'
24+
- python: 3.2
25+
env: ASTROPY_VERSION=stable NUMPY_VERSION=1.6.2 SETUP_CMD='test'
26+
# numpy < 1.6 does not work on py 3.x
27+
28+
# try latest developer version of astropy
29+
- python: 2.7
30+
env: ASTROPY_VERSION=development NUMPY_VERSION=1.7.1 SETUP_CMD='test'
31+
- python: 3.3
32+
env: ASTROPY_VERSION=development NUMPY_VERSION=1.7.1 SETUP_CMD='test'
33+
34+
before_install:
35+
# We do this to make sure we get the dependencies so pip works below
36+
- sudo apt-get update -qq
37+
- sudo apt-get install -qq python-numpy python-sphinx cython libatlas-dev liblapack-dev gfortran
38+
- if [[ $SETUP_CMD == build_sphinx* ]]; then sudo apt-get install -qq python-sphinx graphviz texlive-latex-extra dvipng python-matplotlib; fi
39+
40+
install:
41+
- export PYTHONIOENCODING=UTF8 # just in case
42+
- pip -q install --upgrade "numpy==$NUMPY_VERSION" --use-mirrors
43+
- pip -q install --upgrade Cython --use-mirrors
44+
- if [[ $SETUP_CMD == build_sphinx* ]]; then pip -q install sphinx==1.1.3 --use-mirrors; fi
45+
- if [[ $SETUP_CMD == build_sphinx* ]]; then pip -q install matplotlib --use-mirrors; fi
46+
47+
- if [[ $ASTROPY_VERSION == stable ]]; then pip -q install astropy --use-mirrors; fi
48+
- if [[ $ASTROPY_VERSION == development ]]; then pip -q install git+http://github.com/astropy/astropy.git#egg=astropy --use-mirrors; fi
49+
50+
script:
51+
- python setup.py $SETUP_CMD
52+

‎MANIFEST.in‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
include README.rst
22

3-
include distribute_setup.py
4-
recursive-include packagename *.pyx *.c
3+
include ez_setup.py
4+
include setuptools_bootstrap.py
55

66
recursive-include docs *
77
recursive-include licenses *
88
recursive-include cextern *
99
recursive-include scripts *
1010

11-
exclude *.pyc *.o
11+
exclude *.pyc *.o
1212
prune docs/_build
1313
prune build
14-

‎README.rst‎

Lines changed: 88 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
Affiliated Package Template Instructions
33
========================================
44

5+
If you run into any problems, don't hesitate to ask for help on the
6+
astropy-dev mailing list!
7+
58
This package provides a template for packages that are affiliated with the
69
`Astropy`_ project. This package design mirrors the layout of the main
710
`Astropy`_ repository, as well as reusing much of the helper code used to
@@ -27,57 +30,45 @@ will be clear from context what to do with your particular VCS.
2730
This will download the latest version of the template from `github`_ and
2831
place it in a directory named ``yourpkg``.
2932

30-
* Go into the directory you just created, and open the ``setup.py`` file
31-
with your favorite text editor. Follow the steps below to update it for
32-
your new package.
33-
34-
1. Change the ``PACKAGENAME`` variable to whatever you decide your package
35-
should be named (for examples' sake, we will call it ``yourpkg``). By
36-
tradition/very strong suggestion, python package names should be all
37-
lower-case.
38-
2. Change the ``DESCRIPTION`` variable to a short (one or few sentence)
39-
description of your package.
40-
3. Define a longer description as a string in the ``LONG_DESCRIPTION``
41-
variable. You may want this to be the docstring of your package itself
42-
as Astropy does. In this case, simple add ``import yourpkg`` somewhere
43-
above, and set ``LONG_DESCRIPTION = yourpkg.__doc__``. Alternatively,
44-
you may omit the description by deleting the variable and deleting the
45-
line where it is used in the ``setup()`` function further down.
46-
4. Add your name and email address by changing the ``AUTHOR`` and
47-
``AUTHOR_EMAIL`` variables.
48-
5. If your affiliated package has a website, change ``URL`` to point to that
49-
site. Otherwise, you can leave it pointing to `Astropy`_ or just
50-
delete it.
51-
6. Exit out of your text editor
52-
53-
* Now tell git to remember the changes you just made::
54-
55-
git add setup.py
56-
git commit -m "adjusted setup.py for new project yourpkg"
57-
58-
* Decide what license you want to use to release your source code. If you
59-
don't care and/or are fine with the Astropy license, just edit the file
60-
``licenses/LICENSE.rst`` with your name (or your collaboration's name) at
61-
the top as the licensees. Otherwise, make sure to replace that file with
62-
whatever license you prefer, and update the ``LICENSE`` variable in
63-
``setup.py`` to reflect your choice of license. You also may need to
64-
update the comment at the top of ``packagename/__init__.py`` to reflect your
65-
choice of license. Again, tell git about your changes::
66-
67-
git add licenses/LICENSE.rst
68-
git add setup.py # if you changed the license and modified setup.py
69-
git commit -m "updated license for new project yourpkg"
33+
* Go into the directory you just created, and open the ``setup.cfg``
34+
file with your favorite text editor. Edit the settings in the
35+
``metadata`` section. These values will be used to automatically
36+
replace special placeholders in the affiliated package template.
37+
38+
1. Change the ``package_name`` variable to whatever you decide your
39+
package should be named. By tradition/very strong suggestion,
40+
python package names should be all lower-case.
41+
2. Change the ``description`` variable to a short (one or few
42+
sentence) description of your package.
43+
3. Add your name and email address by changing the ``author`` and
44+
``author_email`` variables.
45+
4. If your affiliated package has a website, change ``url`` to point
46+
to that site. Otherwise, you can leave it pointing to `Astropy`_
47+
or just delete it.
48+
5. Exit out of your text editor
49+
50+
* Update the main package docstring in ``packagename/__init__.py``.
51+
52+
* Decide what license you want to use to release your source code. If
53+
you don't care and/or are fine with the Astropy license, just edit
54+
the file ``licenses/LICENSE.rst`` with your name (or your
55+
collaboration's name) at the top as the licensees. Otherwise, make
56+
sure to replace that file with whatever license you prefer, and
57+
update the ``license`` variable in ``setup.cfg`` to reflect your
58+
choice of license. You also may need to update the comment at the
59+
top of ``packagename/__init__.py`` to reflect your choice of
60+
license.
7061

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

8273
git rm packagename/example_mod.py
8374
git rm scripts/script_example
@@ -86,69 +77,31 @@ will be clear from context what to do with your particular VCS.
8677
git rm -r packagename/example_subpkg
8778
git commit -m "removed examples from package template"
8879

89-
* Now rename the source code directory to match your project's name::
90-
91-
git mv packagename yourpkg
92-
git commit -m "renamed template package source to new project yourpkg"
93-
94-
* Adjust the information in the documentation to match your new project by
95-
editing the ``docs/conf.py`` file.
96-
97-
1. Change the ``project`` variable to your project's name (note that this does
98-
not *need* to be exactly the same as the package name, but that's a
99-
common convention).
100-
2. Change the following lines::
101-
102-
import packagename
103-
# The short X.Y version.
104-
version = packagename.__version__.split('-', 1)[0]
105-
# The full version, including alpha/beta/rc tags.
106-
release = packagename.__version__
107-
108-
109-
to::
110-
111-
import yourpkg
112-
# The short X.Y version.
113-
version = yourpkg.__version__.split('-', 1)[0]
114-
# The full version, including alpha/beta/rc tags.
115-
release = yourpkg.__version__
116-
117-
where ``yourpkg`` is the name of your package.
118-
119-
3. Update the ``copyright`` variable for the current year, and also your name
120-
or the name of your collaboration (e.g.,"2011, John Doe and the
121-
Amazing Package Collaboration.")
122-
4. If you ever expect to output your docs in LaTeX or as a man page, you'll
123-
also want to update the `latex_documents` and `man_pages` variables to
124-
reflect your project, name, and author list.
80+
* Optional: If you're hosting your source code on github, you can
81+
enable a sphinx extension that will link documentation pages
82+
directly to github's web site. To do this, set ``edit_on_github`` in
83+
``setup.cfg`` to ``True`` and set ``github_project`` to the name of
84+
your project on github.
12585

126-
* Pass these changes on to git::
86+
* Move the main source directory to reflect the name of your package.
87+
To tell your DVCS about this move, you should use it, and not ``mv``
88+
directly, to make the move. For example, with git::
12789

128-
git add docs/conf.py
129-
git commit -m "updated documentation for new project yourpkg"
90+
git mv packagename yourpkg
13091

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

13596
git add docs/index.rst
13697
git mv docs/packagename docs/yourpkg
137-
git commit -m "Updated docs to reflect new project yourpkg"
138-
139-
* Adjust the ``MANIFEST.in`` file to reflect your package's name by changing
140-
the line 4 from ``recursive-include packagename *.pyx *.c`` to
141-
``recursive-include yourpkg *.pyx *.c`` and pass this onto git::
142-
143-
... edit MANIFEST.in as described above...
144-
git add MANIFEST.in
145-
git commit -m "updated MANIFEST.in for new project yourpkg"
14698

14799
* Edit this file (``README.rst``) and delete all of this content, and replace it
148-
with a short description of your affiliated package. Inform git::
100+
with a short description of your affiliated package.
101+
102+
* Now tell git to remember the changes you just made::
149103

150-
git add README.rst
151-
git commit -m "replaced README for new project yourpkg"
104+
git commit -a -m "Adjusted for new project yourpkg"
152105

153106
* (This step assumes your affiliated package is hosted as part of the astropy
154107
organization on Github. If it's instead hosted somewhere else, just adjust
@@ -181,6 +134,43 @@ will be clear from context what to do with your particular VCS.
181134
up to the main repository, just switch to the appropriate branch and do
182135
``git push upstream master``.
183136

137+
Additionally, you can set things up to make it easier to pull future
138+
changes to the package template to your affiliated package. Add a remote
139+
for the package template::
140+
141+
git remote add template [email protected]:astropy/package-template.git
142+
143+
Then, each time you want to pull in changes to the package template::
144+
145+
git fetch template
146+
git fetch upstream
147+
148+
# Make your master match the upstream master. This will destroy
149+
# any unmerged commits on your master (which you shouldn't be doing
150+
# work on anyway, according to the standard workflow).
151+
git checkout master
152+
git reset --hard upstream/master
153+
154+
# Merge any recent changes from the package-template
155+
git merge template/master
156+
157+
# ...possibly resolve any conflicts...
158+
159+
# Push to upstream master
160+
git push upstream master
161+
162+
* You should register your package on https://travis-ci.org and modify the
163+
``.travis.yml`` file to make the build pass. This will continuously test
164+
your package for each commit, even pull requests against your main repository
165+
will be automatically tested, so that you notice when something breaks.
166+
For further information see
167+
`here <https://github.com/astropy/astropy/wiki/Continuous-Integration>`_
168+
and for lot's of example ``.travis.yml`` build configurations see
169+
`here <https://github.com/astropy/astropy/wiki/travis-ci-test-status>`_.
170+
Generally you should aim to always have your `master` branch work with
171+
the latest stable as well as the latest development version of astropy
172+
(i.e. the astropy git master branch).
173+
184174
* You're now ready to start doing actual work on your affiliated package. You
185175
will probably want to read over the developer guidelines of the Astropy
186176
documentation, and if you are hosting your code in GitHub, you might also

‎cextern/README.rst‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

0 commit comments

Comments
 (0)