Skip to content

Commit 06548be

Browse files
peterjcpeterjc
committed
Release markup and use restructuredtext with epydoc
Lots of markup tweaking in the building-a-release file. Still needs updating now that the website is on GitHub Pages (see issue #15). Also switched to using restructuredtext as the default with epydoc (was previously plain text).
1 parent ce6be93 commit 06548be

File tree

1 file changed

+150
-120
lines changed

1 file changed

+150
-120
lines changed

‎wiki/Building_a_release.md

+150-120
Original file line numberDiff line numberDiff line change
@@ -32,196 +32,226 @@ The instructions proper
3232
These instructions are for a Unix machine, with a Windows machine also
3333
needed to test and prepare the Windows installers.
3434

35-
1. make sure I have the latest code
35+
1. make sure I have the latest code:
3636

37-
`   drevil:~biopython> git pull origin master`
37+
``` bash
38+
$ git pull origin master
39+
```
3840

3941
2. bump version numbers and set the release data:
4042

41-
- Biopython version - edit Bio/\_\_init\_\_.py
42-
- Biopython Tutorial - update the date/version line in the
43-
Doc/Tutorial.tex file
44-
- Biopython README - fill in the release date
45-
- Make sure to commit the modified files to github.
43+
- Biopython version - edit `Bio/__init__.py`
44+
- Biopython Tutorial - update the date/version line in the
45+
`Doc/Tutorial.tex` file
46+
- Biopython `README` - fill in the release date
47+
- Make sure to commit the modified files to github.
4648

47-
3. make sure the README file is still up to date
49+
3. make sure the `README` file is still up to date
4850

49-
4. add any important info to NEWS or DEPRECATED - you can get a log of
50-
recent git changes like this (adjust the date accordingly):
51+
4. add any important info to `NEWS` or `DEPRECATED` - you can get a
52+
log of recent git changes like this (adjust the date accordingly):
5153

52-
`   git log --since="2009/08/30" --reverse --pretty="medium"`
53-
`   `
54+
``` bash
55+
$ git log --since="2009/08/30" --reverse --pretty="medium"
56+
```
5457

55-
5. make sure CONTRIB still current
58+
5. make sure `CONTRIB` still current
5659

5760
6. make sure setup.py is still up to date
5861

59-
- Are there any new modules which should get installed?
60-
- You don't need to update version in setup.py itself (this is now
61-
done in Bio/\_\_init\_\_.py as described above)
62+
- Are there any new modules which should get installed?
63+
- You don't need to update version in `setup.py` itself
64+
(this is now done in `Bio/__init__.py` as described above)
6265

63-
7. do last check to make sure things are checked in
66+
7. do last check to make sure things are checked in:
6467

65-
`   > rm -r build`
66-
`   > rm Tests/*.pyc`
67-
`   > make clean -C Doc`
68-
`   > git status`
68+
``` bash
69+
$ rm -r build
70+
$ rm Tests/*.pyc
71+
$ make clean -C Doc
72+
$ git status
73+
```
6974

70-
8. build Biopython and do last regression test
75+
8. build Biopython and do last regression test:
7176

72-
`   drevil:~biopython> python setup.py build `
73-
`   drevil:~biopython> python setup.py test`
77+
``` bash
78+
drevil:~biopython> python setup.py build
79+
drevil:~biopython> python setup.py test
80+
```
7481

75-
Ideally do this with a clean checkout on your Windows machine too.
76-
Assuming you have setup your compilers etc appropriately just do this:
82+
Ideally do this with a clean checkout on your Windows machine too.
83+
Assuming you have setup your compilers etc appropriately just do
84+
this:
7785

78-
`   C:\python26\python setup.py build`
79-
`   C:\python26\python setup.py test`
86+
```
87+
C:\python26\python setup.py build
88+
C:\python26\python setup.py test
8089
81-
`   C:\python27\python setup.py build`
82-
`   C:\python27\python setup.py test`
90+
C:\python27\python setup.py build
91+
C:\python27\python setup.py test
8392
84-
`   C:\python33\python setup.py build`
85-
`   C:\python33\python setup.py test`
93+
C:\python33\python setup.py build
94+
C:\python33\python setup.py test
8695
87-
`   C:\python34\python setup.py build`
88-
`   C:\python34\python setup.py test`
96+
C:\python34\python setup.py build
97+
C:\python34\python setup.py test
98+
```
8999

90-
If you are using MinGW, do not forget to add --compiler=mingw32 (or make
91-
it the default on distutils, see the step on building on windows
92-
machines). Also If you are using a modern MinGW compiler, then distutils
93-
of Python will use an option (-mno-cywgin) that is deprecated and will
94-
break gcc. A possible solution is to [edit
95-
distutils](http://bugs.python.org/issue12641), but on recent Python (3.3
96-
as tested) this seems to have been addressed.
100+
If you are using MinGW, do not forget to add `--compiler=mingw32`
101+
(or make it the default on distutils, see the step on building on
102+
Windows machines). Also If you are using a modern MinGW compiler,
103+
then distutils of Python will use an option (`-mno-cywgin`) that
104+
is deprecated and will break gcc. A possible solution is to
105+
[edit distutils](http://bugs.python.org/issue12641), but on
106+
recent Python (3.3 as tested) this seems to have been addressed.
97107

98-
Running the tests simultaneously is risky, as two threads may both try
99-
and read/write to the same temp files.
108+
Running the tests simultaneously is risky, as two threads may both
109+
try to read/write to the same temp files.
100110

101-
9. check out clean version somewhere else
111+
9. check out clean version somewhere else:
102112

103-
`   drevil:~tmp1/> git clone `[`git://github.com/biopython/biopython.git`](git://github.com/biopython/biopython.git)
104-
`   drevil:~tmp1/> cd biopython`
113+
``` bash
114+
drevil:~tmp1/> git clone git://github.com/biopython/biopython.git
115+
drevil:~tmp1/> cd biopython
116+
```
105117

106-
10. make documentation PDF, text and HTML files in Doc
118+
10. make documentation PDF, text and HTML files in Doc:
107119

108-
`   drevil:~biopython> cd Doc`
109-
`   drevil:~biopython/Doc> make`
110-
`   drevil:~biopython/Doc> make clean`
111-
`   drevil:~biopython/Doc> cd ..`
120+
``` bash
121+
drevil:~biopython> cd Doc
122+
drevil:~biopython/Doc> make
123+
drevil:~biopython/Doc> make clean
124+
drevil:~biopython/Doc> cd ..
125+
```
112126

113-
11. make MANIFEST. First, make sure MANIFEST.in up to date.
127+
11. make `MANIFEST`. First, make sure `MANIFEST.in` is up to date.
114128

115-
`   > python setup.py sdist --manifest-only `
129+
``` bash
130+
$ python setup.py sdist --manifest-only
131+
```
116132

117133
12. make the source distribution
118134

119-
`   drevil:~tmp1/biopython> python setup.py sdist --formats=gztar,zip `
135+
``` bash
136+
drevil:~tmp1/biopython> python setup.py sdist --formats=gztar,zip
137+
```
120138

121139
13. untar the file somewhere else
122140

123-
`   drevil:~tmp2> tar -xzvf ../tmp1/biopython/dist/biopython-1.53.tar.gz`
141+
``` bash
142+
drevil:~tmp2> tar -xzvf ../tmp1/biopython/dist/biopython-1.53.tar.gz
143+
```
124144

125-
- Check to make sure it includes the HTML and PDF files under Doc
145+
- Check to make sure it includes the HTML and PDF files under Doc
126146

127147
14. make sure I can build and test it
128148

129-
`   drevil:~tmp2/biopython-1.53/> python setup.py build`
130-
`   drevil:~tmp2/biopython-1.53/> python setup.py test`
131-
`   drevil:~tmp2/biopython-1.53/> python setup.py install --root . `
149+
``` bash
150+
drevil:~tmp2/biopython-1.53/> python setup.py build
151+
drevil:~tmp2/biopython-1.53/> python setup.py test
152+
drevil:~tmp2/biopython-1.53/> python setup.py install --root .
153+
```
132154

133-
A typical source of failure here (on the tests) is the lack of example
134-
files being added to the source distribution: add them to MANIFEST.in
155+
A typical source of failure here (on the tests) is the lack of example
156+
files being added to the source distribution: add them to `MANIFEST.in`
135157

136158
15. Update API documentation using Epydoc (this can often report
137159
otherwise overlooked errors).
138160

139-
- Go to the ./lib/python2.6/site-packages directory. This is the
140-
directory created under your source installation after the install
141-
step above (the name might vary a bit - it should be the place where
142-
the source packages were "installed"). Running epydoc in your git
143-
tree works, but can miss some packages due to import errors.
144-
145-
`   epydoc -v -o ~/api -u `[`http://biopython.org`](http://biopython.org)` -n Biopython --docformat plaintext Bio BioSQL`
146-
`   zip api.zip -r ~/api/`
147-
`   scp api.zip biopython.org:.`
148-
149-
- Move the generated ~/api directory to replace
150-
/home/websites/biopython.org/html/static/DIST/docs/api/ on
151-
biopython.org (aka cloudportal.open-bio.org).
152-
- Also update
153-
/home/websites/biopython.org/html/static/DIST/docs/tutorial with the
154-
tutorial files
161+
- Go to the `./lib/python2.7/site-packages` directory. This is the
162+
directory created under your source installation after the install
163+
step above (the name might vary a bit - it should be the place where
164+
the source packages were "installed"). Running epydoc in your git
165+
tree works, but can miss some packages due to import errors.
166+
167+
``` bash
168+
$ epydoc -v -o ~/api -u http://biopython.org -n Biopython --docformat restructuredtext Bio BioSQL
169+
$ zip api.zip -r ~/api/
170+
$ scp api.zip biopython.org:.
171+
```
172+
173+
- Move the generated `~/api` directory to replace
174+
/home/websites/biopython.org/html/static/DIST/docs/api/ on
175+
biopython.org (aka cloudportal.open-bio.org).
176+
- Also update
177+
/home/websites/biopython.org/html/static/DIST/docs/tutorial with the
178+
tutorial files
155179

156180
16. add git tag
157181

158-
`   drevil:~biopython> git tag biopython-159`
159-
`   drevil:~biopython> git push origin master --tags`
182+
``` bash
183+
$ git tag biopython-159
184+
$ git push origin master --tags
185+
```
160186

161187
17. On your windows machine, build the Windows installers (either from a
162188
clean checkout, or an unzipped copy of the source code bundle made
163189
earlier). Build the installers first, if you do a build/test/install
164190
before hand you seem to get a bloated setup exe. Assuming you have setup
165191
your compilers etc appropriately just do this:
166192

167-
`   C:\python26\python setup.py bdist_wininst`
168-
`   C:\python27\python setup.py bdist_wininst`
169-
`   C:\python33\python setup.py bdist_wininst`
170-
`   C:\python34\python setup.py bdist_wininst`
171-
`   C:\python35\python setup.py bdist_wininst`
172-
`   C:\python35\python setup.py bdist_msi`
173-
174-
If you are using MinGW, you will have to make distutils use it (it will
175-
use a MS compiler by default). Here (contrary to the build step) you
176-
cannot pass the compiler as a parameter. The best solution might be to
177-
[configure
178-
distutils](http://stackoverflow.com/questions/3297254/how-to-use-mingws-gcc-compiler-when-installing-python-package-using-pip)
193+
```
194+
C:\python26\python setup.py bdist_wininst
195+
C:\python27\python setup.py bdist_wininst
196+
C:\python33\python setup.py bdist_wininst
197+
C:\python34\python setup.py bdist_wininst
198+
C:\python35\python setup.py bdist_wininst
199+
C:\python35\python setup.py bdist_msi
200+
```
201+
202+
If you are using MinGW, you will have to make distutils use it (it will
203+
use a MS compiler by default). Here (contrary to the build step) you
204+
cannot pass the compiler as a parameter. The best solution might be to
205+
[configure
206+
distutils](http://stackoverflow.com/questions/3297254/how-to-use-mingws-gcc-compiler-when-installing-python-package-using-pip)
179207

180208
18. Remove any prior Biopython installations on your windows machine,
181209
and confirm the Windows installers work.
182210

183-
19. scp or ftp the .tar.gz, .zip and Windows installer files to the
211+
19. scp or ftp the `.tar.gz`, `.zip` and Windows installer files to the
184212
Biopython website, folder /home/websites/biopython.org/html/static/DIST/
185213
on biopython.org (aka cloudportal.open-bio.org).
186214

187215
20. Upload to the python package index (except for beta/alpha level
188216
releases):
189217

190-
`   > python setup.py register sdist upload`
218+
``` bash
219+
$ python setup.py register sdist upload
220+
```
191221

192-
You need to have a login on pypi and be registered with Biopython to be
193-
able to upload the new version.
222+
You need to have a login on pypi and be registered with Biopython to be
223+
able to upload the new version.
194224

195225
21. Update the website and announce the release:
196226

197-
- before you announce the release, be sure to send your announcement
198-
text to the biopython-dev mailing list for
199-
proof-reading/final corrections.
200-
- add to [main page](Main_Page "wikilink") and [downloads
201-
page](Download "wikilink") (through the wiki), make sure the links
202-
work
203-
- post the announcement on
204-
[news.open-bio.org](http://news.open-bio.org) (which will update the
205-
[news page](News "wikilink") and
206-
[twitter](http://twitter.com/Biopython) via the news feed)
207-
- add the new version to
208-
[RedMine](https://redmine.open-bio.org/projects/biopython)
209-
- send email to biopython@biopython.org and
210-
biopython-announce@biopython.org (see [mailing
211-
lists](Mailing_lists "wikilink"))
212-
- forward the email to Linux packagers e.g.
213-
debian-med@lists.debian.org
227+
- before you announce the release, be sure to send your announcement
228+
text to the biopython-dev mailing list for
229+
proof-reading/final corrections.
230+
- add to [main page](Main_Page "wikilink") and [downloads
231+
page](Download "wikilink") (through the wiki), make sure the links
232+
work
233+
- post the announcement on
234+
[news.open-bio.org](http://news.open-bio.org) (which will update the
235+
[news page](News "wikilink") and
236+
[twitter](http://twitter.com/Biopython) via the news feed)
237+
- add the new version to
238+
[RedMine](https://redmine.open-bio.org/projects/biopython)
239+
- send email to biopython@biopython.org and
240+
biopython-announce@biopython.org (see [mailing
241+
lists](Mailing_lists "wikilink"))
242+
- forward the email to Linux packagers e.g.
243+
debian-med@lists.debian.org
214244

215245
22. Ask Peter, Brad, or Bjoern to prepare a new Galaxy package on
216-
<https://github.com/biopython/galaxy_packages> and upload it to the main
217-
and test Galaxy ToolShed
246+
[biopython/galaxy_packages](https://github.com/biopython/galaxy_packages)
247+
and upload it to the main and test Galaxy ToolShed.
218248

219249
23. Bump version numbers again
220250

221-
- Update Bio/\_\_init\_\_.py version
222-
- Biopython Tutorial - update the date/version line in the
223-
Doc/Tutorial.tex file
224-
- Make sure to commit the modified files to github.
251+
- Update `Bio/__init__.py` version
252+
- Biopython Tutorial - update the date/version line in the
253+
`Doc/Tutorial.tex` file
254+
- Make sure to commit the modified files to github.
225255

226-
Add a plus to the version to note that development is after the said
227-
version. E.g. if you have \_\_version\_\_ = "1.61", make it 1.61+
256+
Add a plus to the version to note that development is after the said
257+
version. E.g. if you have `__version__ = "1.61"`, make it `1.61+`

0 commit comments

Comments
 (0)