Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 192 lines (135 sloc) 6.653 kb
f4dfc7e Pearu Peterson Incr. micro version to 1. Enabled CVS version info in version. Enabled a...
pearu authored
1 .. -*- rest -*-
e1a048d Jarrod Millman updating README
jarrodmillman authored
2 =================================================
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
3 Developing SciPy
e1a048d Jarrod Millman updating README
jarrodmillman authored
4 =================================================
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
5
6 :Author: Pearu Peterson <pearu@cens.ioc.ee>
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
7 :Modified by: Ed Schofield <edschofield@gmail.com>
e1a048d Jarrod Millman updating README
jarrodmillman authored
8 :Modified by: Jarrod Millman <millman AT berkeley.edu>
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
9 :Last changed: $Date$
10 :Revision: $Revision$
11 :Discussions to: scipy-dev@scipy.org
12
c0e1d0a Pearu Peterson Impl. ScipyTest class that will facilitate testing dropped-into-Lib Scip...
pearu authored
13 .. Contents::
14
e1a048d Jarrod Millman updating README
jarrodmillman authored
15
16 What is SciPY?
17 --------------
18
19 SciPy (pronounced "Sigh Pie") is open-source software for mathematics,
20 science, and engineering. It includes modules for statistics, optimization,
21 integration, linear algebra, Fourier transforms, signal and image processing,
22 genetic algorithms, ODE solvers, and more. It is also the name of a very
23 popular conference on scientific programming with Python.
24
25 The SciPy library depends on NumPy, which provides convenient and fast
26 N-dimensional array manipulation. The SciPy library is built to work with
27 NumPy arrays, and provides many user-friendly and efficient numerical routines
28 such as routines for numerical integration and optimization. Together, they
29 run on all popular operating systems, are quick to install, and are free of
30 charge. NumPy and SciPy are easy to use, but powerful enough to be depended
31 upon by some of the world's leading scientists and engineers. If you need to
32 manipulate numbers on a computer and display or publish the results, give
33 SciPy a try!
34
35
36 SciPy structure
37 ---------------
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
38
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
39 SciPy aims at being a robust and efficient "super-package" of a number
40 of modules, each of a non-trivial size and complexity. In order for
41 "SciPy integration" to work flawlessly, all SciPy modules must follow
42 certain rules that are described in this document. Hopefully this
43 document will be helpful for SciPy contributors and developers as a
44 basic reference about the structure of the SciPy package.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
45
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
46 Currently SciPy consists of the following files and directories:
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
47
48 INSTALL.txt
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
49 SciPy prerequisites, installation, testing, and troubleshooting.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
50
51 THANKS.txt
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
52 SciPy developers and contributors. Please keep it up to date!!
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
53
54 DEVELOPERS.txt
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
55 SciPy structure (this document).
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
56
57 setup.py
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
58 Script for building and installing SciPy.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
59
60 MANIFEST.in
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
61 Additions to distutils-generated SciPy tar-balls. Its usage is
62 deprecated.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
63
e13a816 Jarrod Millman few fixes leftover from switch to scipy/ from Lib/
jarrodmillman authored
64 scipy/
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
65 Contains SciPy __init__.py and the directories of SciPy modules.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
66
0c067eb More fixes to docs
edschofield authored
67 SciPy modules
e1a048d Jarrod Millman updating README
jarrodmillman authored
68 +++++++++++++
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
69
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
70 In the following, a *SciPy module* is defined as a Python package, say
e13a816 Jarrod Millman few fixes leftover from switch to scipy/ from Lib/
jarrodmillman authored
71 xxx, that is located in the scipy/ directory. All SciPy modules should
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
72 follow the following conventions:
73
eb18268 Documentation and version updates since 0.4.8 release
edschofield authored
74 * Ideally, each SciPy module should be as self-contained as possible.
75 That is, it should have minimal dependencies on other packages or
76 modules. Even dependencies on other SciPy modules should be kept to a
77 minimum. A dependency on NumPy is of course assumed.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
78
c0e1d0a Pearu Peterson Impl. ScipyTest class that will facilitate testing dropped-into-Lib Scip...
pearu authored
79 * Directory ``xxx/`` must contain
80
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
81 + a file ``setup.py`` that defines
a870025 Pearu Peterson Quick updates to *.txt files.
pearu authored
82 ``configuration(parent_package='',top_path=None)`` function.
7434b18 Pearu Peterson Cleanup and doc updates
pearu authored
83 See below for more details.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
84
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
85 + a file ``info.py``. See below more details.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
86
c0e1d0a Pearu Peterson Impl. ScipyTest class that will facilitate testing dropped-into-Lib Scip...
pearu authored
87 * Directory ``xxx/`` may contain
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
88
c0e1d0a Pearu Peterson Impl. ScipyTest class that will facilitate testing dropped-into-Lib Scip...
pearu authored
89 + a directory ``tests/`` that contains files ``test_<name>.py``
9073df1 Pearu Peterson Incr. micro version number. New style importing hooks will follow soon (...
pearu authored
90 corresponding to modules ``xxx/<name>{.py,.so,/}``. See below for
c0e1d0a Pearu Peterson Impl. ScipyTest class that will facilitate testing dropped-into-Lib Scip...
pearu authored
91 more details.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
92
48e618d Pearu Peterson Doc updates. Hey, scipy is bdist_rpm-able\!
pearu authored
93 + a file ``MANIFEST.in`` that may contain only ``include setup.py`` line.
94 DO NOT specify sources in MANIFEST.in, you must specify all sources
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
95 in setup.py file. Otherwise released SciPy tarballs will miss these sources.
c0e1d0a Pearu Peterson Impl. ScipyTest class that will facilitate testing dropped-into-Lib Scip...
pearu authored
96
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
97 + a directory ``docs/`` for documentation.
01bda66 Pearu Peterson Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
98
a870025 Pearu Peterson Quick updates to *.txt files.
pearu authored
99 For details, read:
9073df1 Pearu Peterson Incr. micro version number. New style importing hooks will follow soon (...
pearu authored
100
a870025 Pearu Peterson Quick updates to *.txt files.
pearu authored
101 http://svn.scipy.org/svn/numpy/trunk/numpy/doc/DISTUTILS.txt
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
102
103
104 Documentation
e1a048d Jarrod Millman updating README
jarrodmillman authored
105 -------------
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
106
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
107 This is an important feature where SciPy is currently lacking. A few
108 SciPy modules have some documentation but they use different formats
109 and are mostly out of date. We could use some help with this.
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
110
111 Currently there are
112
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
113 * A SciPy tutorial by Travis E. Oliphant. This is maintained using LyX.
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
114 The main advantage of this approach is that one can use mathematical
115 formulas in documentation.
116
117 * I (Pearu) have used reStructuredText formated .txt files to document
118 various bits of software. This is mainly because ``docutils`` might
119 become a standard tool to document Python modules. The disadvantage
120 is that it does not support mathematical formulas (though, we might
121 add this feature ourself using e.g. LaTeX syntax).
122
123 * Various text files with almost no formatting and mostly badly out
124 dated.
125
126 * Documentation strings of Python functions, classes, and modules.
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
127 Some SciPy modules are well-documented in this sense, others are very
128 poorly documented. Another issue is that there is no consensus on how
129 to format documentation strings, mainly because we haven't decided
130 which tool to use to generate, for instance, HTML pages of
131 documentation strings.
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
132
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
133 So, we need unique rules for documenting SciPy modules. Here are some
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
134 requirements that documentation tools should satsify:
135
136 * Easy to use. This is important to lower the threshold of developers
137 to use the same documentation utilities.
138
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
139 * In general, all functions that are visible to SciPy end-users, must
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
140 have well-maintained documentation strings.
141
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
142 * Support for mathematical formulas. Since SciPy is a tool for
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
143 scientific work, it is hard to avoid formulas to describe how its
144 modules are good for. So, documentation tools should support LaTeX.
145
146 * Documentation of a feature should be closely related to its
147 interface and implementation. This is important for keeping
148 documentation up to date. One option would be to maintain
149 documentation in source files (and have a tool that extracts
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
150 documentation from sources). The main disadvantage with that is the
151 lack of convenience writing documentation as the editor would be in
152 different mode (e.g. Python mode) from the mode suitable for
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
153 documentation.
154
155 * Differentiation of implementation (e.g. from scanning sources) and
156 concept (e.g. tutorial, users guide, manual) based docs.
157
158
e1a048d Jarrod Millman updating README
jarrodmillman authored
159 Web sites
160 ---------
161
162 The user's site is here
163 http://www.scipy.org/
164
165 The developer's site is here
166 http://projects.scipy.org/scipy/scipy/wiki
167
168
169 Mailing Lists
170 -------------
171
172 Please see the developer's list here
173 http://projects.scipy.org/mailman/listinfo/scipy-devel
174
175
176 Bug reports
177 -----------
178
179 To search for bugs, please use the NIPY Bug Tracker at
180 http://projects.scipy.org/scipy/scipy/query
181
182 To report a bug, please use the NIPY Bug Tracker at
183 http://projects.scipy.org/scipy/scipy/newticket
184
185
186 License information
187 -------------------
9d25a33 Pearu Peterson Doc updates (get_path,SourceFilter). Added discussion section about docu...
pearu authored
188
e1a048d Jarrod Millman updating README
jarrodmillman authored
189 See the file "LICENSE" for information on the history of this
190 software, terms & conditions for usage, and a DISCLAIMER OF ALL
191 WARRANTIES.
Something went wrong with that request. Please try again.