From db0ba1df5ae664e10ca330225541eac8c8c32ba4 2013-11-14 19:21:32 From: Thomas Kluyver Date: 2013-11-14 19:21:32 Subject: [PATCH] Miscellaneous docs fixes --- diff --git a/IPython/core/inputsplitter.py b/IPython/core/inputsplitter.py index 97c199d..315a7a9 100644 --- a/IPython/core/inputsplitter.py +++ b/IPython/core/inputsplitter.py @@ -212,13 +212,13 @@ def get_input_encoding(): #----------------------------------------------------------------------------- class InputSplitter(object): - """An object that can accumulate lines of Python source before execution. + r"""An object that can accumulate lines of Python source before execution. This object is designed to be fed python source line-by-line, using - :meth:`push`. It will return on each push whether the currently pushed - code could be executed already. In addition, it provides a method called - :meth:`push_accepts_more` that can be used to query whether more input - can be pushed into a single interactive block. + :meth:`push`. It will return on each push whether the currently pushed + code could be executed already. In addition, it provides a method called + :meth:`push_accepts_more` that can be used to query whether more input + can be pushed into a single interactive block. This is a simple example of how an interactive terminal-based client can use this tool:: diff --git a/IPython/core/interactiveshell.py b/IPython/core/interactiveshell.py index 41db47f..f05e051 100644 --- a/IPython/core/interactiveshell.py +++ b/IPython/core/interactiveshell.py @@ -131,9 +131,9 @@ def get_default_colors(): class SeparateUnicode(Unicode): - """A Unicode subclass to validate separate_in, separate_out, etc. + r"""A Unicode subclass to validate separate_in, separate_out, etc. - This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'. + This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``. """ def validate(self, obj, value): diff --git a/IPython/core/ultratb.py b/IPython/core/ultratb.py index 8ea0874..a932ec9 100644 --- a/IPython/core/ultratb.py +++ b/IPython/core/ultratb.py @@ -2,7 +2,8 @@ """ ultratb.py -- Spice up your tracebacks! -* ColorTB +**ColorTB** + I've always found it a bit hard to visually parse tracebacks in Python. The ColorTB class is a solution to that problem. It colors the different parts of a traceback in a manner similar to what you would expect from a syntax-highlighting @@ -13,7 +14,8 @@ Installation instructions for ColorTB:: import sys,ultratb sys.excepthook = ultratb.ColorTB() -* VerboseTB +**VerboseTB** + I've also included a port of Ka-Ping Yee's "cgitb.py" that produces all kinds of useful info when a traceback occurs. Ping originally had it spit out HTML and intended it for CGI programmers, but why should they have all the fun? I diff --git a/IPython/html/services/notebooks/handlers.py b/IPython/html/services/notebooks/handlers.py index e52e559..69d0ac4 100644 --- a/IPython/html/services/notebooks/handlers.py +++ b/IPython/html/services/notebooks/handlers.py @@ -145,9 +145,11 @@ class NotebookHandler(IPythonHandler): POST creates new notebooks. The server always decides on the notebook name. - POST /api/notebooks/path : new untitled notebook in path - If content specified, upload a notebook, otherwise start empty. - POST /api/notebooks/path?copy=OtherNotebook.ipynb : new copy of OtherNotebook in path + POST /api/notebooks/path + New untitled notebook in path. If content specified, upload a + notebook, otherwise start empty. + POST /api/notebooks/path?copy=OtherNotebook.ipynb + New copy of OtherNotebook in path """ if name is not None: @@ -171,14 +173,15 @@ class NotebookHandler(IPythonHandler): def put(self, path='', name=None): """Saves the notebook in the location specified by name and path. - PUT /api/notebooks/path/Name.ipynb : Save notebook at path/Name.ipynb - Notebook structure is specified in `content` key of JSON request body. - If content is not specified, create a new empty notebook. - PUT /api/notebooks/path/Name.ipynb?copy=OtherNotebook.ipynb : copy OtherNotebook to Name + PUT is very similar to POST, but the requester specifies the name, + whereas with POST, the server picks the name. - POST and PUT are basically the same. The only difference: - - - with POST, server always picks the name, with PUT the requester does + PUT /api/notebooks/path/Name.ipynb + Save notebook at ``path/Name.ipynb``. Notebook structure is specified + in `content` key of JSON request body. If content is not specified, + create a new empty notebook. + PUT /api/notebooks/path/Name.ipynb?copy=OtherNotebook.ipynb + Copy OtherNotebook to Name """ if name is None: raise web.HTTPError(400, "Only PUT to full names. Use POST for directories.") diff --git a/IPython/kernel/channels.py b/IPython/kernel/channels.py index d514ece..49845bb 100644 --- a/IPython/kernel/channels.py +++ b/IPython/kernel/channels.py @@ -133,9 +133,9 @@ class ZMQSocketChannel(Thread): def stop(self): """Stop the channel's event loop and join its thread. - This calls :method:`Thread.join` and returns when the thread + This calls :meth:`~threading.Thread.join` and returns when the thread terminates. :class:`RuntimeError` will be raised if - :method:`self.start` is called again. + :meth:`~threading.Thread.start` is called again. """ self.join() @@ -430,7 +430,7 @@ class IOPubChannel(ZMQSocketChannel): def flush(self, timeout=1.0): """Immediately processes all pending messages on the iopub channel. - Callers should use this method to ensure that :method:`call_handlers` + Callers should use this method to ensure that :meth:`call_handlers` has been called for all messages that have been received on the 0MQ SUB socket of this channel. diff --git a/IPython/lib/security.py b/IPython/lib/security.py index d5c61cb..eab67bb 100644 --- a/IPython/lib/security.py +++ b/IPython/lib/security.py @@ -49,8 +49,8 @@ def passwd(passphrase=None, algorithm='sha1'): Examples -------- - In [1]: passwd('mypassword') - Out[1]: 'sha1:7cf3:b7d6da294ea9592a9480c8f52e63cd42cfb9dd12' + >>> passwd('mypassword') + 'sha1:7cf3:b7d6da294ea9592a9480c8f52e63cd42cfb9dd12' """ if passphrase is None: @@ -89,16 +89,14 @@ def passwd_check(hashed_passphrase, passphrase): Examples -------- - In [1]: from IPython.lib.security import passwd_check - - In [2]: passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a', - ...: 'mypassword') - Out[2]: True - - In [3]: passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a', - ...: 'anotherpassword') - Out[3]: False - + >>> from IPython.lib.security import passwd_check + >>> passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a', + ... 'mypassword') + True + + >>> passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a', + ... 'anotherpassword') + False """ try: algorithm, salt, pw_digest = hashed_passphrase.split(':', 2) diff --git a/IPython/nbconvert/exporters/export.py b/IPython/nbconvert/exporters/export.py index 21aeeee..b19ffba 100644 --- a/IPython/nbconvert/exporters/export.py +++ b/IPython/nbconvert/exporters/export.py @@ -16,7 +16,7 @@ Module containing single call export functions. from functools import wraps from IPython.nbformat.v3.nbbase import NotebookNode -from IPython.config import Config +from IPython.utils.decorators import undoc from IPython.utils.py3compat import string_types from .exporter import Exporter @@ -32,18 +32,20 @@ from .rst import RSTExporter # Classes #----------------------------------------------------------------------------- +@undoc def DocDecorator(f): #Set docstring of function f.__doc__ = f.__doc__ + """ - nb : Notebook node + nb : :class:`~IPython.nbformat.v3.nbbase.NotebookNode` + The notebook to export. config : config (optional, keyword arg) User configuration instance. resources : dict (optional, keyword arg) Resources used in the conversion process. Returns - ---------- + ------- tuple- output, resources, exporter_instance output : str Jinja 2 output. This is the resulting converted notebook. @@ -55,6 +57,8 @@ def DocDecorator(f): to caller because it provides a 'file_extension' property which specifies what extension the output should be saved as. + Notes + ----- WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT """ @@ -92,11 +96,13 @@ def export(exporter, nb, **kw): """ Export a notebook object using specific exporter class. - exporter : Exporter class type or instance - Class type or instance of the exporter that should be used. If the - method initializes it's own instance of the class, it is ASSUMED that - the class type provided exposes a constructor (__init__) with the same - signature as the base Exporter class. + Parameters + ---------- + exporter : class:`~IPython.nbconvert.exporters.exporter.Exporter` class or instance + Class type or instance of the exporter that should be used. If the + method initializes it's own instance of the class, it is ASSUMED that + the class type provided exposes a constructor (``__init__``) with the same + signature as the base Exporter class. """ #Check arguments @@ -152,6 +158,8 @@ def export_by_name(format_name, nb, **kw): (Inspect) is used to find the template's corresponding explicit export method defined in this module. That method is then called directly. + Parameters + ---------- format_name : str Name of the template style to export to. """ diff --git a/IPython/nbconvert/nbconvertapp.py b/IPython/nbconvert/nbconvertapp.py index 85ab4a4..1c8a62c 100755 --- a/IPython/nbconvert/nbconvertapp.py +++ b/IPython/nbconvert/nbconvertapp.py @@ -77,7 +77,7 @@ nbconvert_flags.update({ class NbConvertApp(BaseIPythonApplication): - """Application used to convert to and from notebook file type (*.ipynb)""" + """Application used to convert from notebook file type (``*.ipynb``)""" name = 'ipython-nbconvert' aliases = nbconvert_aliases