##// END OF EJS Templates
Miscellaneous docs fixes
Thomas Kluyver -
r13597:db0ba1df
parent child
Show More
@@ -212,13 +212,13 def get_input_encoding():
212 #-----------------------------------------------------------------------------
212 #-----------------------------------------------------------------------------
213
213
214 class InputSplitter(object):
214 class InputSplitter(object):
215 """An object that can accumulate lines of Python source before execution.
215 r"""An object that can accumulate lines of Python source before execution.
216
216
217 This object is designed to be fed python source line-by-line, using
217 This object is designed to be fed python source line-by-line, using
218 :meth:`push`. It will return on each push whether the currently pushed
218 :meth:`push`. It will return on each push whether the currently pushed
219 code could be executed already. In addition, it provides a method called
219 code could be executed already. In addition, it provides a method called
220 :meth:`push_accepts_more` that can be used to query whether more input
220 :meth:`push_accepts_more` that can be used to query whether more input
221 can be pushed into a single interactive block.
221 can be pushed into a single interactive block.
222
222
223 This is a simple example of how an interactive terminal-based client can use
223 This is a simple example of how an interactive terminal-based client can use
224 this tool::
224 this tool::
@@ -131,9 +131,9 def get_default_colors():
131
131
132
132
133 class SeparateUnicode(Unicode):
133 class SeparateUnicode(Unicode):
134 """A Unicode subclass to validate separate_in, separate_out, etc.
134 r"""A Unicode subclass to validate separate_in, separate_out, etc.
135
135
136 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
136 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
137 """
137 """
138
138
139 def validate(self, obj, value):
139 def validate(self, obj, value):
@@ -2,7 +2,8
2 """
2 """
3 ultratb.py -- Spice up your tracebacks!
3 ultratb.py -- Spice up your tracebacks!
4
4
5 * ColorTB
5 **ColorTB**
6
6 I've always found it a bit hard to visually parse tracebacks in Python. The
7 I've always found it a bit hard to visually parse tracebacks in Python. The
7 ColorTB class is a solution to that problem. It colors the different parts of a
8 ColorTB class is a solution to that problem. It colors the different parts of a
8 traceback in a manner similar to what you would expect from a syntax-highlighting
9 traceback in a manner similar to what you would expect from a syntax-highlighting
@@ -13,7 +14,8 Installation instructions for ColorTB::
13 import sys,ultratb
14 import sys,ultratb
14 sys.excepthook = ultratb.ColorTB()
15 sys.excepthook = ultratb.ColorTB()
15
16
16 * VerboseTB
17 **VerboseTB**
18
17 I've also included a port of Ka-Ping Yee's "cgitb.py" that produces all kinds
19 I've also included a port of Ka-Ping Yee's "cgitb.py" that produces all kinds
18 of useful info when a traceback occurs. Ping originally had it spit out HTML
20 of useful info when a traceback occurs. Ping originally had it spit out HTML
19 and intended it for CGI programmers, but why should they have all the fun? I
21 and intended it for CGI programmers, but why should they have all the fun? I
@@ -145,9 +145,11 class NotebookHandler(IPythonHandler):
145
145
146 POST creates new notebooks. The server always decides on the notebook name.
146 POST creates new notebooks. The server always decides on the notebook name.
147
147
148 POST /api/notebooks/path : new untitled notebook in path
148 POST /api/notebooks/path
149 If content specified, upload a notebook, otherwise start empty.
149 New untitled notebook in path. If content specified, upload a
150 POST /api/notebooks/path?copy=OtherNotebook.ipynb : new copy of OtherNotebook in path
150 notebook, otherwise start empty.
151 POST /api/notebooks/path?copy=OtherNotebook.ipynb
152 New copy of OtherNotebook in path
151 """
153 """
152
154
153 if name is not None:
155 if name is not None:
@@ -171,14 +173,15 class NotebookHandler(IPythonHandler):
171 def put(self, path='', name=None):
173 def put(self, path='', name=None):
172 """Saves the notebook in the location specified by name and path.
174 """Saves the notebook in the location specified by name and path.
173
175
174 PUT /api/notebooks/path/Name.ipynb : Save notebook at path/Name.ipynb
176 PUT is very similar to POST, but the requester specifies the name,
175 Notebook structure is specified in `content` key of JSON request body.
177 whereas with POST, the server picks the name.
176 If content is not specified, create a new empty notebook.
177 PUT /api/notebooks/path/Name.ipynb?copy=OtherNotebook.ipynb : copy OtherNotebook to Name
178
178
179 POST and PUT are basically the same. The only difference:
179 PUT /api/notebooks/path/Name.ipynb
180
180 Save notebook at ``path/Name.ipynb``. Notebook structure is specified
181 - with POST, server always picks the name, with PUT the requester does
181 in `content` key of JSON request body. If content is not specified,
182 create a new empty notebook.
183 PUT /api/notebooks/path/Name.ipynb?copy=OtherNotebook.ipynb
184 Copy OtherNotebook to Name
182 """
185 """
183 if name is None:
186 if name is None:
184 raise web.HTTPError(400, "Only PUT to full names. Use POST for directories.")
187 raise web.HTTPError(400, "Only PUT to full names. Use POST for directories.")
@@ -133,9 +133,9 class ZMQSocketChannel(Thread):
133 def stop(self):
133 def stop(self):
134 """Stop the channel's event loop and join its thread.
134 """Stop the channel's event loop and join its thread.
135
135
136 This calls :method:`Thread.join` and returns when the thread
136 This calls :meth:`~threading.Thread.join` and returns when the thread
137 terminates. :class:`RuntimeError` will be raised if
137 terminates. :class:`RuntimeError` will be raised if
138 :method:`self.start` is called again.
138 :meth:`~threading.Thread.start` is called again.
139 """
139 """
140 self.join()
140 self.join()
141
141
@@ -430,7 +430,7 class IOPubChannel(ZMQSocketChannel):
430 def flush(self, timeout=1.0):
430 def flush(self, timeout=1.0):
431 """Immediately processes all pending messages on the iopub channel.
431 """Immediately processes all pending messages on the iopub channel.
432
432
433 Callers should use this method to ensure that :method:`call_handlers`
433 Callers should use this method to ensure that :meth:`call_handlers`
434 has been called for all messages that have been received on the
434 has been called for all messages that have been received on the
435 0MQ SUB socket of this channel.
435 0MQ SUB socket of this channel.
436
436
@@ -49,8 +49,8 def passwd(passphrase=None, algorithm='sha1'):
49
49
50 Examples
50 Examples
51 --------
51 --------
52 In [1]: passwd('mypassword')
52 >>> passwd('mypassword')
53 Out[1]: 'sha1:7cf3:b7d6da294ea9592a9480c8f52e63cd42cfb9dd12'
53 'sha1:7cf3:b7d6da294ea9592a9480c8f52e63cd42cfb9dd12'
54
54
55 """
55 """
56 if passphrase is None:
56 if passphrase is None:
@@ -89,16 +89,14 def passwd_check(hashed_passphrase, passphrase):
89
89
90 Examples
90 Examples
91 --------
91 --------
92 In [1]: from IPython.lib.security import passwd_check
92 >>> from IPython.lib.security import passwd_check
93
93 >>> passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a',
94 In [2]: passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a',
94 ... 'mypassword')
95 ...: 'mypassword')
95 True
96 Out[2]: True
96
97
97 >>> passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a',
98 In [3]: passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a',
98 ... 'anotherpassword')
99 ...: 'anotherpassword')
99 False
100 Out[3]: False
101
102 """
100 """
103 try:
101 try:
104 algorithm, salt, pw_digest = hashed_passphrase.split(':', 2)
102 algorithm, salt, pw_digest = hashed_passphrase.split(':', 2)
@@ -16,7 +16,7 Module containing single call export functions.
16 from functools import wraps
16 from functools import wraps
17
17
18 from IPython.nbformat.v3.nbbase import NotebookNode
18 from IPython.nbformat.v3.nbbase import NotebookNode
19 from IPython.config import Config
19 from IPython.utils.decorators import undoc
20 from IPython.utils.py3compat import string_types
20 from IPython.utils.py3compat import string_types
21
21
22 from .exporter import Exporter
22 from .exporter import Exporter
@@ -32,18 +32,20 from .rst import RSTExporter
32 # Classes
32 # Classes
33 #-----------------------------------------------------------------------------
33 #-----------------------------------------------------------------------------
34
34
35 @undoc
35 def DocDecorator(f):
36 def DocDecorator(f):
36
37
37 #Set docstring of function
38 #Set docstring of function
38 f.__doc__ = f.__doc__ + """
39 f.__doc__ = f.__doc__ + """
39 nb : Notebook node
40 nb : :class:`~IPython.nbformat.v3.nbbase.NotebookNode`
41 The notebook to export.
40 config : config (optional, keyword arg)
42 config : config (optional, keyword arg)
41 User configuration instance.
43 User configuration instance.
42 resources : dict (optional, keyword arg)
44 resources : dict (optional, keyword arg)
43 Resources used in the conversion process.
45 Resources used in the conversion process.
44
46
45 Returns
47 Returns
46 ----------
48 -------
47 tuple- output, resources, exporter_instance
49 tuple- output, resources, exporter_instance
48 output : str
50 output : str
49 Jinja 2 output. This is the resulting converted notebook.
51 Jinja 2 output. This is the resulting converted notebook.
@@ -55,6 +57,8 def DocDecorator(f):
55 to caller because it provides a 'file_extension' property which
57 to caller because it provides a 'file_extension' property which
56 specifies what extension the output should be saved as.
58 specifies what extension the output should be saved as.
57
59
60 Notes
61 -----
58 WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
62 WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
59 """
63 """
60
64
@@ -92,11 +96,13 def export(exporter, nb, **kw):
92 """
96 """
93 Export a notebook object using specific exporter class.
97 Export a notebook object using specific exporter class.
94
98
95 exporter : Exporter class type or instance
99 Parameters
96 Class type or instance of the exporter that should be used. If the
100 ----------
97 method initializes it's own instance of the class, it is ASSUMED that
101 exporter : class:`~IPython.nbconvert.exporters.exporter.Exporter` class or instance
98 the class type provided exposes a constructor (__init__) with the same
102 Class type or instance of the exporter that should be used. If the
99 signature as the base Exporter class.
103 method initializes it's own instance of the class, it is ASSUMED that
104 the class type provided exposes a constructor (``__init__``) with the same
105 signature as the base Exporter class.
100 """
106 """
101
107
102 #Check arguments
108 #Check arguments
@@ -152,6 +158,8 def export_by_name(format_name, nb, **kw):
152 (Inspect) is used to find the template's corresponding explicit export
158 (Inspect) is used to find the template's corresponding explicit export
153 method defined in this module. That method is then called directly.
159 method defined in this module. That method is then called directly.
154
160
161 Parameters
162 ----------
155 format_name : str
163 format_name : str
156 Name of the template style to export to.
164 Name of the template style to export to.
157 """
165 """
@@ -77,7 +77,7 nbconvert_flags.update({
77
77
78
78
79 class NbConvertApp(BaseIPythonApplication):
79 class NbConvertApp(BaseIPythonApplication):
80 """Application used to convert to and from notebook file type (*.ipynb)"""
80 """Application used to convert from notebook file type (``*.ipynb``)"""
81
81
82 name = 'ipython-nbconvert'
82 name = 'ipython-nbconvert'
83 aliases = nbconvert_aliases
83 aliases = nbconvert_aliases
General Comments 0
You need to be logged in to leave comments. Login now