Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 192 lines (135 sloc) 6.653 kB
f4dfc7e @pearu Incr. micro version to 1. Enabled CVS version info in version. Enable…
pearu authored
1 .. -*- rest -*-
e1a048d @jarrodmillman updating README
jarrodmillman authored
2 =================================================
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
3 Developing SciPy
e1a048d @jarrodmillman updating README
jarrodmillman authored
4 =================================================
01bda66 @pearu 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 @jarrodmillman updating README
jarrodmillman authored
8 :Modified by: Jarrod Millman <millman AT berkeley.edu>
01bda66 @pearu 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 Impl. ScipyTest class that will facilitate testing dropped-into-Lib S…
pearu authored
13 .. Contents::
14
e1a048d @jarrodmillman 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 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 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 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 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 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 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 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 Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
63
e13a816 @jarrodmillman 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 Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
66
0c067eb More fixes to docs
edschofield authored
67 SciPy modules
e1a048d @jarrodmillman updating README
jarrodmillman authored
68 +++++++++++++
01bda66 @pearu 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 @jarrodmillman 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 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 Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
78
c0e1d0a @pearu Impl. ScipyTest class that will facilitate testing dropped-into-Lib S…
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 Quick updates to *.txt files.
pearu authored
82 ``configuration(parent_package='',top_path=None)`` function.
7434b18 @pearu Cleanup and doc updates
pearu authored
83 See below for more details.
01bda66 @pearu 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 Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
86
c0e1d0a @pearu Impl. ScipyTest class that will facilitate testing dropped-into-Lib S…
pearu authored
87 * Directory ``xxx/`` may contain
01bda66 @pearu Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
88
c0e1d0a @pearu Impl. ScipyTest class that will facilitate testing dropped-into-Lib S…
pearu authored
89 + a directory ``tests/`` that contains files ``test_<name>.py``
9073df1 @pearu Incr. micro version number. New style importing hooks will follow soo…
pearu authored
90 corresponding to modules ``xxx/<name>{.py,.so,/}``. See below for
c0e1d0a @pearu Impl. ScipyTest class that will facilitate testing dropped-into-Lib S…
pearu authored
91 more details.
01bda66 @pearu Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
92
48e618d @pearu 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 Impl. ScipyTest class that will facilitate testing dropped-into-Lib S…
pearu authored
96
aea889b Documentation updates folded back from 0.4.4 branch
edschofield authored
97 + a directory ``docs/`` for documentation.
01bda66 @pearu Introducing DEVELOPERS.txt and making .txt files ReST compatible
pearu authored
98
a870025 @pearu Quick updates to *.txt files.
pearu authored
99 For details, read:
9073df1 @pearu Incr. micro version number. New style importing hooks will follow soo…
pearu authored
100
a870025 @pearu Quick updates to *.txt files.
pearu authored
101 http://svn.scipy.org/svn/numpy/trunk/numpy/doc/DISTUTILS.txt
9d25a33 @pearu Doc updates (get_path,SourceFilter). Added discussion section about d…
pearu authored
102
103
104 Documentation
e1a048d @jarrodmillman updating README
jarrodmillman authored
105 -------------
9d25a33 @pearu Doc updates (get_path,SourceFilter). Added discussion section about d…
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 Doc updates (get_path,SourceFilter). Added discussion section about d…
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 Doc updates (get_path,SourceFilter). Added discussion section about d…
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 Doc updates (get_path,SourceFilter). Added discussion section about d…
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 Doc updates (get_path,SourceFilter). Added discussion section about d…
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 Doc updates (get_path,SourceFilter). Added discussion section about d…
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 Doc updates (get_path,SourceFilter). Added discussion section about d…
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 Doc updates (get_path,SourceFilter). Added discussion section about d…
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 @jarrodmillman 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 Doc updates (get_path,SourceFilter). Added discussion section about d…
pearu authored
188
e1a048d @jarrodmillman 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.