##// END OF EJS Templates
More doc updates....
Fernando Perez -
Show More
@@ -0,0 +1,141 b''
1 ==============
2 Coding guide
3 ==============
4
5
6 Coding conventions
7 ==================
8
9 In general, we'll try to follow the standard Python style conventions as
10 described in Python's `PEP 8`_, the official Python Style Guide.
11
12 .. _PEP 8: http://www.python.org/peps/pep-0008.html
13
14 Other comments:
15
16 - In a large file, top level classes and functions should be separated by 2-3
17 lines to make it easier to separate them visually.
18
19 - Use 4 spaces for indentation, *never* use hard tabs.
20
21 - Keep the ordering of methods the same in classes that have the same methods.
22 This is particularly true for classes that implement similar interfaces and
23 for interfaces that are similar.
24
25 Naming conventions
26 ------------------
27
28 In terms of naming conventions, we'll follow the guidelines of PEP 8. Some of
29 the existing code doesn't honor this perfectly, but for all new IPython code
30 (and much existing code is being refactored), we'll use:
31
32 - All ``lowercase`` module names.
33
34 - ``CamelCase`` for class names.
35
36 - ``lowercase_with_underscores`` for methods, functions, variables and
37 attributes.
38
39 This may be confusing as some of the existing codebase uses a different
40 convention (``lowerCamelCase`` for methods and attributes). Slowly, we will
41 move IPython over to the new convention, providing shadow names for backward
42 compatibility in public interfaces.
43
44 There are, however, some important exceptions to these rules. In some cases,
45 IPython code will interface with packages (Twisted, Wx, Qt) that use other
46 conventions. At some level this makes it impossible to adhere to our own
47 standards at all times. In particular, when subclassing classes that use other
48 naming conventions, you must follow their naming conventions. To deal with
49 cases like this, we propose the following policy:
50
51 - If you are subclassing a class that uses different conventions, use its
52 naming conventions throughout your subclass. Thus, if you are creating a
53 Twisted Protocol class, used Twisted's
54 ``namingSchemeForMethodsAndAttributes.``
55
56 - All IPython's official interfaces should use our conventions. In some cases
57 this will mean that you need to provide shadow names (first implement
58 ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all
59 costs, but it will probably be necessary at times. But, please use this
60 sparingly!
61
62 Implementation-specific *private* methods will use
63 ``_single_underscore_prefix``. Names with a leading double underscore will
64 *only* be used in special cases, as they makes subclassing difficult (such
65 names are not easily seen by child classes).
66
67 Occasionally some run-in lowercase names are used, but mostly for very short
68 names or where we are implementing methods very similar to existing ones in a
69 base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
70 established precedent).
71
72 The old IPython codebase has a big mix of classes and modules prefixed with an
73 explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
74 upon, as namespaces offer cleaner prefixing. The only case where this approach
75 is justified is for classes which are expected to be imported into external
76 namespaces and a very generic name (like Shell) is too likely to clash with
77 something else. We'll need to revisit this issue as we clean up and refactor
78 the code, but in general we should remove as many unnecessary ``IP``/``ip``
79 prefixes as possible. However, if a prefix seems absolutely necessary the more
80 specific ``IPY`` or ``ipy`` are preferred.
81
82
83 .. _devel-testing:
84
85 Testing system
86 ==============
87
88 It is extremely important that all code contributed to IPython has tests. Tests
89 should be written as unittests, doctests or as entities that the `Nose`_
90 testing package will find. Regardless of how the tests are written, we will use
91 `Nose`_ for discovering and running the tests. `Nose`_ will be required to run
92 the IPython test suite, but will not be required to simply use IPython.
93
94 .. _Nose: http://code.google.com/p/python-nose/
95
96 Tests of `Twisted`__ using code should be written by subclassing the
97 ``TestCase`` class that comes with ``twisted.trial.unittest``. When this is
98 done, `Nose`_ will be able to run the tests and the twisted reactor will be
99 handled correctly.
100
101 .. __: http://www.twistedmatrix.com
102
103 Each subpackage in IPython should have its own ``tests`` directory that
104 contains all of the tests for that subpackage. This allows each subpackage to
105 be self-contained. If a subpackage has any dependencies beyond the Python
106 standard library, the tests for that subpackage should be skipped if the
107 dependencies are not found. This is very important so users don't get tests
108 failing simply because they don't have dependencies.
109
110 We also need to look into use Noses ability to tag tests to allow a more
111 modular approach of running tests.
112
113 .. _devel-config:
114
115 Configuration system
116 ====================
117
118 IPython uses `.ini`_ files for configuration purposes. This represents a huge
119 improvement over the configuration system used in IPython. IPython works with
120 these files using the `ConfigObj`_ package, which IPython includes as
121 ``ipython1/external/configobj.py``.
122
123 Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of
124 IPython should contain a ``config`` subdirectory that contains all of the
125 configuration information for the subpackage. To see how configuration
126 information is defined (along with defaults) see at the examples in
127 ``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how
128 the configuration information is used, see examples in
129 ``ipython1/kernel/scripts/ipengine.py``.
130
131 Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We
132 are calling this new layer, ``tconfig``, as it will use a `Traits`_-like
133 validation model. We won't actually use `Traits`_, but will implement
134 something similar in pure Python. But, even in this new system, we will still
135 use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you
136 are interested in working on this part of IPython. The current prototype of
137 ``tconfig`` is located in the IPython sandbox.
138
139 .. _.ini: http://docs.python.org/lib/module-ConfigParser.html
140 .. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
141 .. _Traits: http://code.enthought.com/traits/
@@ -0,0 +1,76 b''
1 Documenting IPython
2 ===================
3
4 Standalone documentation
5 ------------------------
6
7 All standalone documentation should be written in plain text (``.txt``) files
8 using `reStructuredText`_ for markup and formatting. All such documentation
9 should be placed in the top level directory ``docs`` of the IPython source
10 tree. Or, when appropriate, a suitably named subdirectory should be used. The
11 documentation in this location will serve as the main source for IPython
12 documentation and all existing documentation should be converted to this
13 format.
14
15 In the future, the text files in the ``docs`` directory will be used to
16 generate all forms of documentation for IPython. This include documentation on
17 the IPython website as well as *pdf* documentation.
18
19 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
20
21 A bit of shell code:
22
23 .. code-block:: bash
24
25 cd /tmp
26 echo "My home directory is: $HOME"
27 ls
28
29 A bit of Python code:
30
31 .. code-block:: python
32
33 for i in range(10):
34 print i,
35 print "A big number:",2**34
36
37 An interactive Python session:
38
39 .. code-block:: python
40
41 >>> from IPython import genutils
42 >>> genutils.get_ipython_dir()
43 '/home/fperez/.ipython'
44
45
46 An IPython session:
47
48 .. code-block:: ipython
49
50 In [8]: import IPython
51
52 In [9]: print "This IPython is version:",IPython.__version__
53 This IPython is version: 0.9.1
54
55
56
57 Docstring format
58 ----------------
59
60 Good docstrings are very important. All new code will use `Epydoc`_ for
61 generating API docs, so we will follow the `Epydoc`_ conventions. More
62 specifically, we will use `reStructuredText`_ for markup and formatting, since
63 it is understood by a wide variety of tools. This means that if in the future
64 we have any reason to change from `Epydoc`_ to something else, we'll have fewer
65 transition pains.
66
67 Details about using `reStructuredText`_ for docstrings can be found `here
68 <http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
69
70 .. _Epydoc: http://epydoc.sourceforge.net/
71
72 Additional PEPs of interest regarding documentation of code:
73
74 - `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
75 - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
76 - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
@@ -1,10 +1,13 b''
1 ==================
1 ===========================
2 Development
2 IPython Developer's Guide
3 ==================
3 ===========================
4
4
5 .. toctree::
5 .. toctree::
6 :maxdepth: 2
6 :maxdepth: 2
7
7
8 development.txt
8 overview.txt
9 coding_guide.txt
10 doc_guide.txt
9 roadmap.txt
11 roadmap.txt
12
10 notification_blueprint.txt
13 notification_blueprint.txt
@@ -1,16 +1,16 b''
1 .. This file has a lot of bash but little python, set default role
2
3 .. highlight:: bash
4
1 .. _development:
5 .. _development:
2
6
3 ==============================
7 ==============================
4 IPython development guidelines
8 IPython development overview
5 ==============================
9 ==============================
6
10
7
8 Overview
9 ========
10
11 Currently, IPython's development tree contains all of the code that used to be
11 Currently, IPython's development tree contains all of the code that used to be
12 part of IPython since the project's inception in 2001, plus all of the effort
12 part of IPython since the project's inception in 2001, plus all of the effort
13 that was known for a while (roughly 2004-2008) as `IPython1'. The IPyhton1
13 that was known for a while (roughly 2004-2008) as ``IPython1``. The IPyhton1
14 development was meant to be an effort to:
14 development was meant to be an effort to:
15
15
16 1. Clean up the existing codebase and write lots of tests.
16 1. Clean up the existing codebase and write lots of tests.
@@ -23,8 +23,13 b' development was meant to be an effort to:'
23 While the third goal may seem a bit unrelated to the main focus of IPython, it
23 While the third goal may seem a bit unrelated to the main focus of IPython, it
24 turns out that the technologies required for this goal are nearly identical
24 turns out that the technologies required for this goal are nearly identical
25 with those required for goal two. This is the main reason the interactive
25 with those required for goal two. This is the main reason the interactive
26 parallel computing capabilities are being put into IPython proper. Currently
26 parallel computing capabilities are being put into IPython proper.
27 the third of these goals is furthest along.
27
28 In the summer of 2008, the IPython1 code was merged back into the mainline, and
29 now there is a unified codebase. While the above goals aren't completely
30 implemented for the older code, we do have a proper :ref:`testing system
31 <devel-testing>` in place (though this is still evolving), unified
32 documentation and partial implementations of the more separated components.
28
33
29 This document describes IPython from the perspective of developers.
34 This document describes IPython from the perspective of developers.
30
35
@@ -44,12 +49,14 b' subpackages will have its own:'
44
49
45 - **Tests**. Each subpackage shoud have its own ``tests`` subdirectory that
50 - **Tests**. Each subpackage shoud have its own ``tests`` subdirectory that
46 contains all of the tests for that package. For information about writing
51 contains all of the tests for that package. For information about writing
47 tests for IPython, see the `Testing System`_ section of this document.
52 tests for IPython, see the :ref:`Testing System <devel-testing>` section of
53 this document.
48
54
49 - **Configuration**. Each subpackage should have its own ``config``
55 - **Configuration**. Each subpackage should have its own ``config``
50 subdirectory that contains the configuration information for the components
56 subdirectory that contains the configuration information for the components
51 of the subpackage. For information about how the IPython configuration
57 of the subpackage. For information about how the IPython configuration
52 system works, see the `Configuration System`_ section of this document.
58 system works, see the :ref:`Configuration System <devel-config>` section of
59 this document.
53
60
54 - **Scripts**. Each subpackage should have its own ``scripts`` subdirectory
61 - **Scripts**. Each subpackage should have its own ``scripts`` subdirectory
55 that contains all of the command line scripts associated with the subpackage.
62 that contains all of the command line scripts associated with the subpackage.
@@ -116,15 +123,12 b' Specific subpackages'
116 today 's IPython. Other frontends will likely be more powerful and based
123 today 's IPython. Other frontends will likely be more powerful and based
117 on GUI toolkits.
124 on GUI toolkits.
118
125
119 ``notebook``
120 An application that allows users to work with IPython notebooks.
121
122 ``tools``
126 ``tools``
123 This is where general utilities go.
127 This is where general utilities go.
124
128
125
129
126 Version control
130 Version control workflow
127 ===============
131 ========================
128
132
129 All IPython development today is done using the `Bazaar`__ system for
133 All IPython development today is done using the `Bazaar`__ system for
130 distributed version control and the `Launchpad`__ site for code hosting and bug
134 distributed version control and the `Launchpad`__ site for code hosting and bug
@@ -140,9 +144,7 b" for IPython you'll eventually want to have a Launchpad account (free) so you"
140 can publish your own code on the site for review and merging, but small
144 can publish your own code on the site for review and merging, but small
141 contributions can be simply sent via email to the IPython list as patches.
145 contributions can be simply sent via email to the IPython list as patches.
142
146
143 Start by creating what Bazaar calls a `shared repository`_:
147 Start by creating what Bazaar calls a `shared repository`_::
144
145 .. sourcecode:: bash
146
148
147 # You can choose any name you want instead of "ipython-repo"
149 # You can choose any name you want instead of "ipython-repo"
148 bzr init-repo ipython-repo
150 bzr init-repo ipython-repo
@@ -152,9 +154,7 b' Start by creating what Bazaar calls a `shared repository`_:'
152 This creates an empty repository where a lot of related branches can be kept,
154 This creates an empty repository where a lot of related branches can be kept,
153 and they all reuse common storage. This way, many operations are very fast and
155 and they all reuse common storage. This way, many operations are very fast and
154 take up less space. Now, go to the newly created repository and make a local
156 take up less space. Now, go to the newly created repository and make a local
155 branch of the public trunk:
157 branch of the public trunk::
156
157 .. sourcecode:: bash
158
158
159 cd ipython-repo
159 cd ipython-repo
160 # This makes a local copy of the public trunk called "trunk-lp"
160 # This makes a local copy of the public trunk called "trunk-lp"
@@ -162,9 +162,7 b' branch of the public trunk:'
162
162
163 The ``trunk-lp`` branch is meant to always be a pristine copy of the public
163 The ``trunk-lp`` branch is meant to always be a pristine copy of the public
164 trunk. From here, make a personal development copy of the public trunk, where
164 trunk. From here, make a personal development copy of the public trunk, where
165 you'll make your changes:
165 you'll make your changes::
166
167 .. sourcecode:: bash
168
166
169 bzr branch trunk-lp trunk-dev
167 bzr branch trunk-lp trunk-dev
170
168
@@ -180,9 +178,7 b' is to make branches to contain specific feature implementations until they are'
180 ready to be merged).
178 ready to be merged).
181
179
182 The typical work cycle will be to make changes in ``trunk-dev`` and then commit
180 The typical work cycle will be to make changes in ``trunk-dev`` and then commit
183 those changes as often as needed:
181 those changes as often as needed::
184
185 .. sourcecode:: bash
186
182
187 cd trunk-dev
183 cd trunk-dev
188 # ... implement cool new feature...
184 # ... implement cool new feature...
@@ -207,17 +203,13 b' atomic change, the bzr log should give an excellent view of the project, and'
207 the ``--short`` log option becomes a nice summary.
203 the ``--short`` log option becomes a nice summary.
208
204
209 As you work on the branch, it's a good idea to frequently keep your copy of the
205 As you work on the branch, it's a good idea to frequently keep your copy of the
210 trunk updated with respect to Launchpad. This is done via:
206 trunk updated with respect to Launchpad. This is done via::
211
212 .. sourcecode:: bash
213
207
214 cd trunk-lp
208 cd trunk-lp
215 bzr pull
209 bzr pull
216
210
217 Bazaar can then merge any changes that were done to the public trunk into your
211 Bazaar can then merge any changes that were done to the public trunk into your
218 local branch via:
212 local branch via::
219
220 .. sourcecode:: bash
221
213
222 cd trunk-dev
214 cd trunk-dev
223 bzr merge ../trunk-lp
215 bzr merge ../trunk-lp
@@ -227,16 +219,13 b' This workflow ensures that a local copy stays in sync with the public trunk,'
227 while allowing for local development to be pushed back for public review.
219 while allowing for local development to be pushed back for public review.
228
220
229 Once your changes are ready for review, you can push them to Launchpad where
221 Once your changes are ready for review, you can push them to Launchpad where
230 the IPython team can review them and give you feedback. The first time, use:
222 the IPython team can review them and give you feedback. The first time, use::
231
223
232 .. sourcecode:: bash
224 bzr push --remember \
233
225 bzr+ssh://<you>@bazaar.launchpad.net/~<you>/ipython/trunk-dev
234 bzr push --remember bzr+ssh://<you>@bazaar.launchpad.net/~<you>/ipython/trunk-dev
235
226
236 where ``<you>`` is your Launchpad user name. This will make this branch
227 where ``<you>`` is your Launchpad user name. This will make this branch
237 publicly visible to all. In subsequent uses you can simply run in the branch:
228 publicly visible to all. In subsequent uses you can simply run in the branch::
238
239 .. sourcecode:: bash
240
229
241 bzr push
230 bzr push
242
231
@@ -249,10 +238,10 b' publicly visible to all. In subsequent uses you can simply run in the branch:'
249 on how to upload your keys.
238 on how to upload your keys.
250
239
251 Once the branch is publicly visible, using the launchpad interface it can be
240 Once the branch is publicly visible, using the launchpad interface it can be
252 marked for merging with the link ``Propose for merging into another branch``,
241 marked for merging with the link marked *"Propose for merging into another
253 leaving the default choice of trunk as its target. This way, Launchpad tracks
242 branch"*, leaving the default choice of trunk as its target. This way,
254 what changes of this branch are new with respect to the trunk, others in the
243 Launchpad tracks what changes of this branch are new with respect to the trunk,
255 team can review it, and merge the changes into the trunk.
244 others in the team can review it, and merge the changes into the trunk.
256
245
257 The IPython team has a policy of reviewing all code (both from core members of
246 The IPython team has a policy of reviewing all code (both from core members of
258 the team and from external contributors) before merging it. Code should be
247 the team and from external contributors) before merging it. Code should be
@@ -262,226 +251,6 b" contribution to the project, and we've found that peer review of code is an"
262 excellent way to improve the quality of everyone's work.
251 excellent way to improve the quality of everyone's work.
263
252
264
253
265 Coding conventions
266 ==================
267
268 General
269 -------
270
271 In general, we'll try to follow the standard Python style conventions as
272 described here:
273
274 - `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_
275
276
277 Other comments:
278
279 - In a large file, top level classes and functions should be
280 separated by 2-3 lines to make it easier to separate them visually.
281 - Use 4 spaces for indentation.
282 - Keep the ordering of methods the same in classes that have the same
283 methods. This is particularly true for classes that implement
284 similar interfaces and for interfaces that are similar.
285
286 Naming conventions
287 ------------------
288
289 In terms of naming conventions, we'll follow the guidelines from the `Style
290 Guide for Python Code`_.
291
292 For all new IPython code (and much existing code is being refactored), we'll use:
293
294 - All ``lowercase`` module names.
295
296 - ``CamelCase`` for class names.
297
298 - ``lowercase_with_underscores`` for methods, functions, variables and
299 attributes.
300
301 This may be confusing as most of the existing IPython codebase uses a different
302 convention (``lowerCamelCase`` for methods and attributes). Slowly, we will
303 move IPython over to the new convention, providing shadow names for backward
304 compatibility in public interfaces.
305
306 There are, however, some important exceptions to these rules. In some cases,
307 IPython code will interface with packages (Twisted, Wx, Qt) that use other
308 conventions. At some level this makes it impossible to adhere to our own
309 standards at all times. In particular, when subclassing classes that use other
310 naming conventions, you must follow their naming conventions. To deal with
311 cases like this, we propose the following policy:
312
313 - If you are subclassing a class that uses different conventions, use its
314 naming conventions throughout your subclass. Thus, if you are creating a
315 Twisted Protocol class, used Twisted's
316 ``namingSchemeForMethodsAndAttributes.``
317
318 - All IPython's official interfaces should use our conventions. In some cases
319 this will mean that you need to provide shadow names (first implement
320 ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all
321 costs, but it will probably be necessary at times. But, please use this
322 sparingly!
323
324 Implementation-specific *private* methods will use
325 ``_single_underscore_prefix``. Names with a leading double underscore will
326 *only* be used in special cases, as they makes subclassing difficult (such
327 names are not easily seen by child classes).
328
329 Occasionally some run-in lowercase names are used, but mostly for very short
330 names or where we are implementing methods very similar to existing ones in a
331 base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
332 established precedent).
333
334 The old IPython codebase has a big mix of classes and modules prefixed with an
335 explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
336 upon, as namespaces offer cleaner prefixing. The only case where this approach
337 is justified is for classes which are expected to be imported into external
338 namespaces and a very generic name (like Shell) is too likely to clash with
339 something else. We'll need to revisit this issue as we clean up and refactor
340 the code, but in general we should remove as many unnecessary ``IP``/``ip``
341 prefixes as possible. However, if a prefix seems absolutely necessary the more
342 specific ``IPY`` or ``ipy`` are preferred.
343
344
345 Documentation
346 =============
347
348 Standalone documentation
349 ------------------------
350
351 All standalone documentation should be written in plain text (``.txt``) files
352 using `reStructuredText`_ for markup and formatting. All such documentation
353 should be placed in the top level directory ``docs`` of the IPython source
354 tree. Or, when appropriate, a suitably named subdirectory should be used. The
355 documentation in this location will serve as the main source for IPython
356 documentation and all existing documentation should be converted to this
357 format.
358
359 In the future, the text files in the ``docs`` directory will be used to
360 generate all forms of documentation for IPython. This include documentation on
361 the IPython website as well as *pdf* documentation.
362
363 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
364
365 A bit of shell code:
366
367 .. sourcecode:: bash
368
369 cd /tmp
370 echo "My home directory is: $HOME"
371 ls
372
373 A bit of Python code:
374
375 .. sourcecode:: python
376
377 for i in range(10):
378 print i,
379 print "A big number:",2**34
380
381 An interactive Python session:
382
383 .. sourcecode:: python
384
385 >>> from IPython import genutils
386 >>> genutils.get_ipython_dir()
387 '/home/fperez/.ipython'
388
389
390 An IPython session:
391
392 .. sourcecode:: ipython
393
394 In [8]: import IPython
395
396 In [9]: print "This IPython is version:",IPython.__version__
397 This IPython is version: 0.9.1
398
399
400
401 Docstring format
402 ----------------
403
404 Good docstrings are very important. All new code will use `Epydoc`_ for
405 generating API docs, so we will follow the `Epydoc`_ conventions. More
406 specifically, we will use `reStructuredText`_ for markup and formatting, since
407 it is understood by a wide variety of tools. This means that if in the future
408 we have any reason to change from `Epydoc`_ to something else, we'll have fewer
409 transition pains.
410
411 Details about using `reStructuredText`_ for docstrings can be found `here
412 <http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
413
414 .. _Epydoc: http://epydoc.sourceforge.net/
415
416 Additional PEPs of interest regarding documentation of code:
417
418 - `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
419 - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
420 - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
421
422
423
424 .. _devel_testing:
425
426 Testing system
427 ==============
428
429 It is extremely important that all code contributed to IPython has tests. Tests
430 should be written as unittests, doctests or as entities that the `Nose`_
431 testing package will find. Regardless of how the tests are written, we will use
432 `Nose`_ for discovering and running the tests. `Nose`_ will be required to run
433 the IPython test suite, but will not be required to simply use IPython.
434
435 .. _Nose: http://code.google.com/p/python-nose/
436
437 Tests of `Twisted`__ using code should be written by subclassing the
438 ``TestCase`` class that comes with ``twisted.trial.unittest``. When this is
439 done, `Nose`_ will be able to run the tests and the twisted reactor will be
440 handled correctly.
441
442 .. __: http://www.twistedmatrix.com
443
444 Each subpackage in IPython should have its own ``tests`` directory that
445 contains all of the tests for that subpackage. This allows each subpackage to
446 be self-contained. If a subpackage has any dependencies beyond the Python
447 standard library, the tests for that subpackage should be skipped if the
448 dependencies are not found. This is very important so users don't get tests
449 failing simply because they don't have dependencies.
450
451 We also need to look into use Noses ability to tag tests to allow a more
452 modular approach of running tests.
453
454 .. _devel_config:
455
456 Configuration system
457 ====================
458
459 IPython uses `.ini`_ files for configuration purposes. This represents a huge
460 improvement over the configuration system used in IPython. IPython works with
461 these files using the `ConfigObj`_ package, which IPython includes as
462 ``ipython1/external/configobj.py``.
463
464 Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of
465 IPython should contain a ``config`` subdirectory that contains all of the
466 configuration information for the subpackage. To see how configuration
467 information is defined (along with defaults) see at the examples in
468 ``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how
469 the configuration information is used, see examples in
470 ``ipython1/kernel/scripts/ipengine.py``.
471
472 Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We
473 are calling this new layer, ``tconfig``, as it will use a `Traits`_-like
474 validation model. We won't actually use `Traits`_, but will implement
475 something similar in pure Python. But, even in this new system, we will still
476 use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you
477 are interested in working on this part of IPython. The current prototype of
478 ``tconfig`` is located in the IPython sandbox.
479
480 .. _.ini: http://docs.python.org/lib/module-ConfigParser.html
481 .. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
482 .. _Traits: http://code.enthought.com/traits/
483
484
485 Installation and testing scenarios
254 Installation and testing scenarios
486 ==================================
255 ==================================
487
256
@@ -489,43 +258,54 b' This section outlines the various scenarios that we need to test before we'
489 release an IPython version. These scenarios represent different ways of
258 release an IPython version. These scenarios represent different ways of
490 installing IPython and its dependencies.
259 installing IPython and its dependencies.
491
260
261
492 Installation scenarios under Linux and OS X
262 Installation scenarios under Linux and OS X
493 -------------------------------------------
263 -------------------------------------------
494
264
495 1. Install from tarball using ``python setup.py install``.
265 1. Install from tarball using ``python setup.py install``.
496 a. With only readline+nose dependencies installed.
266
497 b. With all dependencies installed (readline, zope.interface, Twisted,
267 * With only readline+nose dependencies installed.
498 foolscap, Sphinx, nose, pyOpenSSL).
268
499
269 * With all dependencies installed (readline, zope.interface, Twisted,
500 2. Install using easy_install.
270 foolscap, Sphinx, nose, pyOpenSSL).
271
272 2. Install using easy_install.
273
274 * With only readline+nose dependencies installed.
275
276 * Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg``
501
277
502 a. With only readline+nose dependencies installed.
278 * Optional dependency sets:
503 i. Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg``
279 ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]``
504 ii. Optional dependency sets: ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]``
505
280
506 b. With all dependencies already installed.
281 * With all dependencies already installed.
507
282
508
283
509 Installation scenarios under Win32
284 Installation scenarios under Win32
510 ----------------------------------
285 ----------------------------------
511
286
512 1. Install everything from .exe installers
287 #. Install everything from .exe installers
513 2. easy_install?
288 #. easy_install?
514
289
515
290
516 Tests to run for these scenarios
291 Tests to run for these scenarios
517 --------------------------------
292 --------------------------------
518
293
519 1. Run the full test suite.
294 #. Run the full test suite.
520 2. Start a controller and engines and try a few things by hand.
295
521 a. Using ipcluster.
296 #. Start a controller and engines and try a few things by hand.
522 b. Using ipcontroller/ipengine by hand.
297
298 * Using ipcluster.
299 * Using ipcontroller/ipengine by hand.
300
301 #. Run a few of the parallel examples.
302
303 #. Try the kernel with and without security with and without PyOpenSSL
304 installed.
305
306 #. Beat on the IPython terminal a bunch.
523
307
524 3. Run a few of the parallel examples.
308 #. Make sure that furl files are being put in proper locations.
525 4. Try the kernel with and without security with and without PyOpenSSL
526 installed.
527 5. Beat on the IPython terminal a bunch.
528 6. Make sure that furl files are being put in proper locations.
529
309
530
310
531 Release checklist
311 Release checklist
@@ -1,3 +1,7 b''
1 .. There's little Python in this file, so make the default language bash.
2
3 .. highlight:: bash
4
1 Overview
5 Overview
2 ========
6 ========
3
7
@@ -42,31 +46,25 b' Installation using easy_install'
42 -------------------------------
46 -------------------------------
43
47
44 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
48 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
45 to use :command:`easy_install`:
49 to use :command:`easy_install`::
46
47 .. sourcecode:: bash
48
50
49 easy_install IPython
51 easy_install IPython
50
52
51 Unless you've written a custom distutils script as explained here_, that will
53 Unless you've written a custom distutils script as explained `here`__, that will
52 try to install either in a default system-wide location, which may require
54 try to install either in a default system-wide location, which may require
53 administrator access. If that is the case, you can either run the command with
55 administrator access. If that is the case, you can either run the command with
54 root privileges:
56 root privileges::
55
56 .. sourcecode:: bash
57
57
58 sudo easy_install IPython
58 sudo easy_install IPython
59
59
60 or you can specify an alternate location, for example:
60 or you can specify an alternate location, for example::
61
62 .. sourcecode:: bash
63
61
64 easy_install --prefix=~/usr/local IPython
62 easy_install --prefix=~/usr/local IPython
65
63
66 where this assumes that ``~/usr/local`` is a valid prefix for you to install
64 where this assumes that ``~/usr/local`` is a valid prefix for you to install
67 packages to in your user account.
65 packages to in your user account.
68
66
69 .. _here: http://docs.python.org/install/index.html#inst-config-files
67 .. __: http://docs.python.org/install/index.html#inst-config-files
70
68
71
69
72 Installation from source
70 Installation from source
@@ -75,9 +73,7 b' Installation from source'
75 If you don't want to use :command:`easy_install`, or don't have it installed,
73 If you don't want to use :command:`easy_install`, or don't have it installed,
76 just grab the latest stable build of IPython from `here
74 just grab the latest stable build of IPython from `here
77 <http://ipython.scipy.org/dist/>`_. Then do the following (using the
75 <http://ipython.scipy.org/dist/>`_. Then do the following (using the
78 appropriate version number):
76 appropriate version number)::
79
80 .. sourcecode:: bash
81
77
82 tar -xzf ipython.tar.gz
78 tar -xzf ipython.tar.gz
83 cd ipython
79 cd ipython
@@ -91,11 +87,13 b' Windows'
91
87
92 There are a few caveats for Windows users. The main issue is that a basic ``python setup.py install`` approach won't create ``.bat`` file or Start Menu shortcuts, which most users want. To get an installation with these, there are two choices:
88 There are a few caveats for Windows users. The main issue is that a basic ``python setup.py install`` approach won't create ``.bat`` file or Start Menu shortcuts, which most users want. To get an installation with these, there are two choices:
93
89
94 1. Install using :command:`easy_install`.
90 #. Install using :command:`easy_install`.
95
91
96 2. Install using our binary ``.exe`` Windows installer, which can be found at `here <http://ipython.scipy.org/dist/>`_
92 #. Install using our binary ``.exe`` Windows installer, which can be found at
93 `here <http://ipython.scipy.org/dist/>`_
97
94
98 3. Install from source, but using :mod:`setuptools` (``python setupegg.py install``).
95 #. Install from source, but using :mod:`setuptools` (``python setupegg.py
96 install``).
99
97
100 Installing the development version
98 Installing the development version
101 ----------------------------------
99 ----------------------------------
@@ -104,8 +102,6 b' It is also possible to install the development version of IPython from our'
104 `Bazaar <http://bazaar-vcs.org/>`_ source code repository. To do this you will
102 `Bazaar <http://bazaar-vcs.org/>`_ source code repository. To do this you will
105 need to have Bazaar installed on your system. Then just do::
103 need to have Bazaar installed on your system. Then just do::
106
104
107 .. sourcecode:: bash
108
109 bzr branch lp:ipython
105 bzr branch lp:ipython
110 cd ipython
106 cd ipython
111 python setup.py install
107 python setup.py install
@@ -114,18 +110,17 b" Again, this last step on Windows won't create ``.bat`` files or Start Menu short"
114
110
115 Some users want to be able to follow the development branch as it changes. If
111 Some users want to be able to follow the development branch as it changes. If
116 you have :mod:`setuptools` installed, this is easy. Simply replace the last
112 you have :mod:`setuptools` installed, this is easy. Simply replace the last
117 step by:
113 step by::
118
119 .. sourcecode:: bash
120
114
121 python setupegg.py develop
115 python setupegg.py develop
122
116
123 This creates links in the right places and installs the command line script to the appropriate places. Then, if you want to update your IPython at any time, just do:
117 This creates links in the right places and installs the command line script to
124
118 the appropriate places. Then, if you want to update your IPython at any time,
125 .. sourcecode:: bash
119 just do::
126
120
127 bzr pull
121 bzr pull
128
122
123
129 Basic optional dependencies
124 Basic optional dependencies
130 ===========================
125 ===========================
131
126
@@ -140,7 +135,9 b' If you are comfortable installing these things yourself, have at it, otherwise r'
140 readline
135 readline
141 --------
136 --------
142
137
143 In principle, all Python distributions should come with a working :mod:`readline` module. But, reality is not quite that simple. There are two common situations where you won't have a working :mod:`readline` module:
138 In principle, all Python distributions should come with a working
139 :mod:`readline` module. But, reality is not quite that simple. There are two
140 common situations where you won't have a working :mod:`readline` module:
144
141
145 * If you are using the built-in Python on Mac OS X.
142 * If you are using the built-in Python on Mac OS X.
146
143
@@ -153,9 +150,7 b' many of the issues related to the differences between readline and libedit have'
153 been resolved. For many users, libedit may be sufficient.
150 been resolved. For many users, libedit may be sufficient.
154
151
155 Most users on OS X will want to get the full :mod:`readline` module. To get a
152 Most users on OS X will want to get the full :mod:`readline` module. To get a
156 working :mod:`readline` module, just do (with :mod:`setuptools` installed):
153 working :mod:`readline` module, just do (with :mod:`setuptools` installed)::
157
158 .. sourcecode:: bash
159
154
160 easy_install readline
155 easy_install readline
161
156
@@ -181,23 +176,17 b' nose'
181
176
182 To run the IPython test suite you will need the :mod:`nose` package. Nose
177 To run the IPython test suite you will need the :mod:`nose` package. Nose
183 provides a great way of sniffing out and running all of the IPython tests. The
178 provides a great way of sniffing out and running all of the IPython tests. The
184 simplest way of getting nose, is to use :command:`easy_install`:
179 simplest way of getting nose, is to use :command:`easy_install`::
185
186 .. sourcecode:: bash
187
180
188 easy_install nose
181 easy_install nose
189
182
190 Another way of getting this is to do:
183 Another way of getting this is to do::
191
192 .. sourcecode:: bash
193
184
194 easy_install IPython[test]
185 easy_install IPython[test]
195
186
196 For more installation options, see the `nose website
187 For more installation options, see the `nose website
197 <http://somethingaboutorange.com/mrl/projects/nose/>`_. Once you have nose
188 <http://somethingaboutorange.com/mrl/projects/nose/>`_. Once you have nose
198 installed, you can run IPython's test suite using the iptest command:
189 installed, you can run IPython's test suite using the iptest command::
199
200 .. sourcecode:: bash
201
190
202 iptest
191 iptest
203
192
@@ -206,9 +195,7 b' pexpect'
206 -------
195 -------
207
196
208 The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's
197 The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's
209 :command:`irunner` script. On Unix platforms (including OS X), just do:
198 :command:`irunner` script. On Unix platforms (including OS X), just do::
210
211 .. sourcecode:: bash
212
199
213 easy_install pexpect
200 easy_install pexpect
214
201
@@ -227,9 +214,7 b' features require a number of additional packages:'
227 * pyOpenSSL (security for network connections)
214 * pyOpenSSL (security for network connections)
228
215
229 On a Unix style platform (including OS X), if you want to use
216 On a Unix style platform (including OS X), if you want to use
230 :mod:`setuptools`, you can just do:
217 :mod:`setuptools`, you can just do::
231
232 .. sourcecode:: bash
233
218
234 easy_install IPython[kernel] # the first three
219 easy_install IPython[kernel] # the first three
235 easy_install IPython[security] # pyOpenSSL
220 easy_install IPython[security] # pyOpenSSL
@@ -238,9 +223,7 b' zope.interface and Twisted'
238 --------------------------
223 --------------------------
239
224
240 On Unix style platforms (including OS X), the simplest way of getting the these
225 On Unix style platforms (including OS X), the simplest way of getting the these
241 is to use :command:`easy_install`:
226 is to use :command:`easy_install`::
242
243 .. sourcecode:: bash
244
227
245 easy_install zope.interface
228 easy_install zope.interface
246 easy_install Twisted
229 easy_install Twisted
@@ -260,9 +243,7 b' Foolscap'
260 Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to
243 Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to
261 implement our parallel computing features.
244 implement our parallel computing features.
262
245
263 On all platforms a simple:
246 On all platforms a simple::
264
265 .. sourcecode:: bash
266
247
267 easy_install foolscap
248 easy_install foolscap
268
249
@@ -297,4 +278,4 b' a nice wxPython based IPython GUI. As you would expect, this GUI requires'
297 wxPython. Most Linux distributions have wxPython packages available and the
278 wxPython. Most Linux distributions have wxPython packages available and the
298 built-in Python on OS X comes with wxPython preinstalled. For Windows, a
279 built-in Python on OS X comes with wxPython preinstalled. For Windows, a
299 binary installer is available on the `wxPython website
280 binary installer is available on the `wxPython website
300 <http://www.wxpython.org/>`_. No newline at end of file
281 <http://www.wxpython.org/>`_.
General Comments 0
You need to be logged in to leave comments. Login now