##// END OF EJS Templates
Miscellaneous docs fixes
Thomas Kluyver -
Show More
@@ -162,7 +162,7 b' class Tracer(object):'
162
162
163 def decorate_fn_with_doc(new_fn, old_fn, additional_text=""):
163 def decorate_fn_with_doc(new_fn, old_fn, additional_text=""):
164 """Make new_fn have old_fn's doc string. This is particularly useful
164 """Make new_fn have old_fn's doc string. This is particularly useful
165 for the do_... commands that hook into the help system.
165 for the ``do_...`` commands that hook into the help system.
166 Adapted from from a comp.lang.python posting
166 Adapted from from a comp.lang.python posting
167 by Duncan Booth."""
167 by Duncan Booth."""
168 def wrapper(*args, **kw):
168 def wrapper(*args, **kw):
@@ -1,26 +1,21 b''
1 """hooks for IPython.
1 """Hooks for IPython.
2
2
3 In Python, it is possible to overwrite any method of any object if you really
3 In Python, it is possible to overwrite any method of any object if you really
4 want to. But IPython exposes a few 'hooks', methods which are _designed_ to
4 want to. But IPython exposes a few 'hooks', methods which are *designed* to
5 be overwritten by users for customization purposes. This module defines the
5 be overwritten by users for customization purposes. This module defines the
6 default versions of all such hooks, which get used by IPython if not
6 default versions of all such hooks, which get used by IPython if not
7 overridden by the user.
7 overridden by the user.
8
8
9 hooks are simple functions, but they should be declared with 'self' as their
9 Hooks are simple functions, but they should be declared with ``self`` as their
10 first argument, because when activated they are registered into IPython as
10 first argument, because when activated they are registered into IPython as
11 instance methods. The self argument will be the IPython running instance
11 instance methods. The self argument will be the IPython running instance
12 itself, so hooks have full access to the entire IPython object.
12 itself, so hooks have full access to the entire IPython object.
13
13
14 If you wish to define a new hook and activate it, you need to put the
14 If you wish to define a new hook and activate it, you can make an :doc:`extension
15 necessary code into a python file which can be either imported or execfile()'d
15 </config/extensions/index>` or a :ref:`startup script <startup_files>`. For
16 from within your profile's ipython_config.py configuration.
16 example, you could use a startup file like this::
17
18 For example, suppose that you have a module called 'myiphooks' in your
19 PYTHONPATH, which contains the following definition:
20
17
21 import os
18 import os
22 from IPython.core import ipapi
23 ip = ipapi.get()
24
19
25 def calljed(self,filename, linenum):
20 def calljed(self,filename, linenum):
26 "My editor hook calls the jed editor directly."
21 "My editor hook calls the jed editor directly."
@@ -28,10 +23,9 b' def calljed(self,filename, linenum):'
28 if os.system('jed +%d %s' % (linenum,filename)) != 0:
23 if os.system('jed +%d %s' % (linenum,filename)) != 0:
29 raise TryNext()
24 raise TryNext()
30
25
26 def load_ipython_extension(ip):
31 ip.set_hook('editor', calljed)
27 ip.set_hook('editor', calljed)
32
28
33 You can then enable the functionality by doing 'import myiphooks'
34 somewhere in your configuration files or ipython command line.
35 """
29 """
36
30
37 #*****************************************************************************
31 #*****************************************************************************
@@ -1902,10 +1902,10 b' class InteractiveShell(SingletonConfigurable):'
1902
1902
1903 Requires readline.
1903 Requires readline.
1904
1904
1905 Example:
1905 Example::
1906
1906
1907 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1907 In [1]: _ip.set_next_input("Hello Word")
1908 [D:\ipython]|2> Hello Word_ # cursor is here
1908 In [2]: Hello Word_ # cursor is here
1909 """
1909 """
1910 self.rl_next_input = py3compat.cast_bytes_py2(s)
1910 self.rl_next_input = py3compat.cast_bytes_py2(s)
1911
1911
@@ -2828,12 +2828,11 b' class InteractiveShell(SingletonConfigurable):'
2828 This turns on support for matplotlib, preloads into the interactive
2828 This turns on support for matplotlib, preloads into the interactive
2829 namespace all of numpy and pylab, and configures IPython to correctly
2829 namespace all of numpy and pylab, and configures IPython to correctly
2830 interact with the GUI event loop. The GUI backend to be used can be
2830 interact with the GUI event loop. The GUI backend to be used can be
2831 optionally selected with the optional :param:`gui` argument.
2831 optionally selected with the optional ``gui`` argument.
2832
2832
2833 Parameters
2833 Parameters
2834 ----------
2834 ----------
2835 gui : optional, string
2835 gui : optional, string
2836
2837 If given, dictates the choice of matplotlib GUI backend to use
2836 If given, dictates the choice of matplotlib GUI backend to use
2838 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2837 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2839 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2838 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
@@ -105,12 +105,19 b' class HistoryMagics(Magics):'
105
105
106 By default, all input history from the current session is displayed.
106 By default, all input history from the current session is displayed.
107 Ranges of history can be indicated using the syntax:
107 Ranges of history can be indicated using the syntax:
108 4 : Line 4, current session
108
109 4-6 : Lines 4-6, current session
109 ``4``
110 243/1-5: Lines 1-5, session 243
110 Line 4, current session
111 ~2/7 : Line 7, session 2 before current
111 ``4-6``
112 ~8/1-~6/5 : From the first line of 8 sessions ago, to the fifth line
112 Lines 4-6, current session
113 of 6 sessions ago.
113 ``243/1-5``
114 Lines 1-5, session 243
115 ``~2/7``
116 Line 7, session 2 before current
117 ``~8/1-~6/5``
118 From the first line of 8 sessions ago, to the fifth line of 6
119 sessions ago.
120
114 Multiple ranges can be entered, separated by spaces
121 Multiple ranges can be entered, separated by spaces
115
122
116 The same syntax is used by %macro, %save, %edit, %rerun
123 The same syntax is used by %macro, %save, %edit, %rerun
@@ -57,8 +57,8 b' def page(strng, start=0, screen_lines=0, pager_cmd=None,'
57 converted to HTML with docutils. Note that if docutils is not found,
57 converted to HTML with docutils. Note that if docutils is not found,
58 this option is silently ignored.
58 this option is silently ignored.
59
59
60 Note
60 Notes
61 ----
61 -----
62
62
63 Only one of the ``html`` and ``auto_html`` options can be given, not
63 Only one of the ``html`` and ``auto_html`` options can be given, not
64 both.
64 both.
@@ -420,9 +420,9 b' class TBTools(object):'
420 class ListTB(TBTools):
420 class ListTB(TBTools):
421 """Print traceback information from a traceback list, with optional color.
421 """Print traceback information from a traceback list, with optional color.
422
422
423 Calling: requires 3 arguments:
423 Calling requires 3 arguments: (etype, evalue, elist)
424 (etype, evalue, elist)
424 as would be obtained by::
425 as would be obtained by:
425
426 etype, evalue, tb = sys.exc_info()
426 etype, evalue, tb = sys.exc_info()
427 if tb:
427 if tb:
428 elist = traceback.extract_tb(tb)
428 elist = traceback.extract_tb(tb)
@@ -1130,7 +1130,7 b' class AutoFormattedTB(FormattedTB):'
1130
1130
1131 It will find out about exceptions by itself.
1131 It will find out about exceptions by itself.
1132
1132
1133 A brief example:
1133 A brief example::
1134
1134
1135 AutoTB = AutoFormattedTB(mode = 'Verbose',color_scheme='Linux')
1135 AutoTB = AutoFormattedTB(mode = 'Verbose',color_scheme='Linux')
1136 try:
1136 try:
@@ -59,12 +59,12 b' class FileLink(object):'
59
59
60 e.g. to embed a link that was generated in the IPython notebook as my/data.txt
60 e.g. to embed a link that was generated in the IPython notebook as my/data.txt
61
61
62 you would do:
62 you would do::
63
63
64 local_file = FileLink("my/data.txt")
64 local_file = FileLink("my/data.txt")
65 display(local_file)
65 display(local_file)
66
66
67 or in the HTML notebook, just
67 or in the HTML notebook, just::
68
68
69 FileLink("my/data.txt")
69 FileLink("my/data.txt")
70 """
70 """
@@ -77,13 +77,17 b' class FileLink(object):'
77 result_html_prefix='',
77 result_html_prefix='',
78 result_html_suffix='<br>'):
78 result_html_suffix='<br>'):
79 """
79 """
80 path : path to the file or directory that should be formatted
80 Parameters
81 directory_prefix : prefix to be prepended to all files to form a
81 ----------
82 working link [default: 'files']
82 path : str
83 result_html_prefix : text to append to beginning to link
83 path to the file or directory that should be formatted
84 [default: none]
84 directory_prefix : str
85 result_html_suffix : text to append at the end of link
85 prefix to be prepended to all files to form a working link [default:
86 [default: '<br>']
86 'files']
87 result_html_prefix : str
88 text to append to beginning to link [default: none]
89 result_html_suffix : str
90 text to append at the end of link [default: '<br>']
87 """
91 """
88 if isdir(path):
92 if isdir(path):
89 raise ValueError,\
93 raise ValueError,\
@@ -500,7 +500,7 b' def enable_gui(gui=None, app=None):'
500 For toolkits that have the concept of a global app, you can supply an
500 For toolkits that have the concept of a global app, you can supply an
501 existing one. If not given, the toolkit will be probed for one, and if
501 existing one. If not given, the toolkit will be probed for one, and if
502 none is found, a new one will be created. Note that GTK does not have
502 none is found, a new one will be created. Note that GTK does not have
503 this concept, and passing an app if `gui`=="GTK" will raise an error.
503 this concept, and passing an app if ``gui=="GTK"`` will raise an error.
504
504
505 Returns
505 Returns
506 -------
506 -------
1 NO CONTENT: modified file
NO CONTENT: modified file
@@ -97,6 +97,7 b' def parse_test_output(txt):'
97 txt : str
97 txt : str
98 Text output of a test run, assumed to contain a line of one of the
98 Text output of a test run, assumed to contain a line of one of the
99 following forms::
99 following forms::
100
100 'FAILED (errors=1)'
101 'FAILED (errors=1)'
101 'FAILED (failures=1)'
102 'FAILED (failures=1)'
102 'FAILED (errors=1, failures=1)'
103 'FAILED (errors=1, failures=1)'
@@ -20,9 +20,9 b' import locale'
20 def get_stream_enc(stream, default=None):
20 def get_stream_enc(stream, default=None):
21 """Return the given stream's encoding or a default.
21 """Return the given stream's encoding or a default.
22
22
23 There are cases where sys.std* might not actually be a stream, so
23 There are cases where ``sys.std*`` might not actually be a stream, so
24 check for the encoding attribute prior to returning it, and return
24 check for the encoding attribute prior to returning it, and return
25 a default if it doesn't exist or evaluates as False. `default'
25 a default if it doesn't exist or evaluates as False. ``default``
26 is None if not provided.
26 is None if not provided.
27 """
27 """
28 if not hasattr(stream, 'encoding') or not stream.encoding:
28 if not hasattr(stream, 'encoding') or not stream.encoding:
@@ -17,7 +17,7 b' def nested(*managers):'
17
17
18 The one advantage of this function over the multiple manager form of the
18 The one advantage of this function over the multiple manager form of the
19 with statement is that argument unpacking allows it to be
19 with statement is that argument unpacking allows it to be
20 used with a variable number of context managers as follows:
20 used with a variable number of context managers as follows::
21
21
22 with nested(*managers):
22 with nested(*managers):
23 do_something()
23 do_something()
@@ -119,7 +119,7 b' class NotificationCenter(object):'
119 ----------
119 ----------
120 callback : callable
120 callback : callable
121 The callable that will be called by :meth:`post_notification`
121 The callable that will be called by :meth:`post_notification`
122 as ``callback(ntype, sender, *args, **kwargs)
122 as ``callback(ntype, sender, *args, **kwargs)``
123 ntype : hashable
123 ntype : hashable
124 The notification type. If None, all notifications from sender
124 The notification type. If None, all notifications from sender
125 will be posted.
125 will be posted.
@@ -770,8 +770,8 b' def _get_or_default(mylist, i, default=None):'
770 def compute_item_matrix(items, empty=None, *args, **kwargs) :
770 def compute_item_matrix(items, empty=None, *args, **kwargs) :
771 """Returns a nested list, and info to columnize items
771 """Returns a nested list, and info to columnize items
772
772
773 Parameters :
773 Parameters
774 ------------
774 ----------
775
775
776 items :
776 items :
777 list of strings to columize
777 list of strings to columize
@@ -782,8 +782,8 b' def compute_item_matrix(items, empty=None, *args, **kwargs) :'
782 displaywidth : int (default=80)
782 displaywidth : int (default=80)
783 The width of the area onto wich the columns should enter
783 The width of the area onto wich the columns should enter
784
784
785 Returns :
785 Returns
786 ---------
786 -------
787
787
788 Returns a tuple of (strings_matrix, dict_info)
788 Returns a tuple of (strings_matrix, dict_info)
789
789
@@ -802,8 +802,8 b' def compute_item_matrix(items, empty=None, *args, **kwargs) :'
802 columns_width : list of with of each columns
802 columns_width : list of with of each columns
803 optimal_separator_width : best separator width between columns
803 optimal_separator_width : best separator width between columns
804
804
805 Exemple :
805 Examples
806 ---------
806 --------
807
807
808 In [1]: l = ['aaa','b','cc','d','eeeee','f','g','h','i','j','k','l']
808 In [1]: l = ['aaa','b','cc','d','eeeee','f','g','h','i','j','k','l']
809 ...: compute_item_matrix(l,displaywidth=12)
809 ...: compute_item_matrix(l,displaywidth=12)
@@ -57,7 +57,9 b" if __name__ == '__main__':"
57 r'\.testing\.mkdoctests']
57 r'\.testing\.mkdoctests']
58 # Now, generate the outputs
58 # Now, generate the outputs
59 docwriter.write_api_docs(outdir)
59 docwriter.write_api_docs(outdir)
60 docwriter.write_index(outdir, 'gen',
60 # Write index with .rst extension - we can include it, but Sphinx won't try
61 # to compile it
62 docwriter.write_index(outdir, 'gen.rst',
61 relative_to = pjoin('source','api')
63 relative_to = pjoin('source','api')
62 )
64 )
63 print '%d files written' % len(docwriter.written_modules)
65 print '%d files written' % len(docwriter.written_modules)
@@ -9,4 +9,4 b''
9 :Release: |version|
9 :Release: |version|
10 :Date: |today|
10 :Date: |today|
11
11
12 .. include:: generated/gen.txt
12 .. include:: generated/gen.rst
@@ -5,4 +5,4 b' storemagic'
5 ==========
5 ==========
6
6
7 .. automodule:: IPython.extensions.storemagic
7 .. automodule:: IPython.extensions.storemagic
8 :members: magic_store
8 :members: store
@@ -394,6 +394,8 b' convenience function :func:`IPython.utils.path.get_security_file`, which will re'
394 the absolute path to a security file from its filename and [optionally] profile
394 the absolute path to a security file from its filename and [optionally] profile
395 name.
395 name.
396
396
397 .. _startup_files:
398
397 Startup Files
399 Startup Files
398 -------------
400 -------------
399
401
@@ -440,7 +442,7 b" to your config file. Key/Value arguments *always* take a value, separated by '='"
440 and no spaces.
442 and no spaces.
441
443
442 Common Arguments
444 Common Arguments
443 ****************
445 ----------------
444
446
445 Since the strictness and verbosity of the KVLoader above are not ideal for everyday
447 Since the strictness and verbosity of the KVLoader above are not ideal for everyday
446 use, common arguments can be specified as flags_ or aliases_.
448 use, common arguments can be specified as flags_ or aliases_.
@@ -454,7 +456,7 b' that are single characters, in which case they can be specified with a single ``'
454 $> ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg
456 $> ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg
455
457
456 Aliases
458 Aliases
457 -------
459 *******
458
460
459 For convenience, applications have a mapping of commonly used traits, so you don't have
461 For convenience, applications have a mapping of commonly used traits, so you don't have
460 to specify the whole class name:
462 to specify the whole class name:
@@ -468,7 +470,7 b' to specify the whole class name:'
468 $> ipython --BaseIPythonApplication.profile='myprofile'
470 $> ipython --BaseIPythonApplication.profile='myprofile'
469
471
470 Flags
472 Flags
471 -----
473 *****
472
474
473 Applications can also be passed **flags**. Flags are options that take no
475 Applications can also be passed **flags**. Flags are options that take no
474 arguments. They are simply wrappers for
476 arguments. They are simply wrappers for
@@ -491,7 +493,7 b' For instance:'
491 $> ipython --TerminalIPythonApp.display_banner=False
493 $> ipython --TerminalIPythonApp.display_banner=False
492
494
493 Subcommands
495 Subcommands
494 ***********
496 -----------
495
497
496
498
497 Some IPython applications have **subcommands**. Subcommands are modeled after
499 Some IPython applications have **subcommands**. Subcommands are modeled after
@@ -166,7 +166,7 b' An example (with automagic on) should clarify all this:'
166 /home/fperez/ipython
166 /home/fperez/ipython
167
167
168 Defining your own magics
168 Defining your own magics
169 ~~~~~~~~~~~~~~~~~~~~~~~~
169 ++++++++++++++++++++++++
170
170
171 There are two main ways to define your own magic functions: from standalone
171 There are two main ways to define your own magic functions: from standalone
172 functions and by inheriting from a base class provided by IPython:
172 functions and by inheriting from a base class provided by IPython:
@@ -681,7 +681,7 b' available.'
681 exec_lines in the config file.
681 exec_lines in the config file.
682
682
683
683
684 .. _credits_011::
684 .. _credits_011:
685
685
686 Credits
686 Credits
687 -------
687 -------
@@ -309,7 +309,7 b' Development summary and credits'
309 The previous version (IPython 0.11) was released on July 31 2011, so this
309 The previous version (IPython 0.11) was released on July 31 2011, so this
310 release cycle was roughly 4 1/2 months long, we closed a total of 515 issues,
310 release cycle was roughly 4 1/2 months long, we closed a total of 515 issues,
311 257 pull requests and 258 regular issues (a :ref:`detailed list
311 257 pull requests and 258 regular issues (a :ref:`detailed list
312 <issues_list_012>`_ is available).
312 <issues_list_012>` is available).
313
313
314 Many users and developers contributed code, features, bug reports and ideas to
314 Many users and developers contributed code, features, bug reports and ideas to
315 this release. Please do not hesitate in contacting us if we've failed to
315 this release. Please do not hesitate in contacting us if we've failed to
@@ -378,18 +378,15 b' class ApiDocWriter(object):'
378 modules = self.discover_modules()
378 modules = self.discover_modules()
379 self.write_modules_api(modules,outdir)
379 self.write_modules_api(modules,outdir)
380
380
381 def write_index(self, outdir, froot='gen', relative_to=None):
381 def write_index(self, outdir, path='gen.rst', relative_to=None):
382 """Make a reST API index file from written files
382 """Make a reST API index file from written files
383
383
384 Parameters
384 Parameters
385 ----------
385 ----------
386 path : string
387 Filename to write index to
388 outdir : string
386 outdir : string
389 Directory to which to write generated index file
387 Directory to which to write generated index file
390 froot : string, optional
388 path : string
391 root (filename without extension) of filename to write to
389 Filename to write index to
392 Defaults to 'gen'. We add ``self.rst_extension``.
393 relative_to : string
390 relative_to : string
394 path to which written filenames are relative. This
391 path to which written filenames are relative. This
395 component of the written file path will be removed from
392 component of the written file path will be removed from
@@ -399,7 +396,7 b' class ApiDocWriter(object):'
399 if self.written_modules is None:
396 if self.written_modules is None:
400 raise ValueError('No modules written')
397 raise ValueError('No modules written')
401 # Get full filename path
398 # Get full filename path
402 path = os.path.join(outdir, froot+self.rst_extension)
399 path = os.path.join(outdir, path)
403 # Path written into index is relative to rootpath
400 # Path written into index is relative to rootpath
404 if relative_to is not None:
401 if relative_to is not None:
405 relpath = outdir.replace(relative_to + os.path.sep, '')
402 relpath = outdir.replace(relative_to + os.path.sep, '')
General Comments 0
You need to be logged in to leave comments. Login now