Magic Arguments & Docstrings #2415

Open
bfroehle opened this Issue Sep 18, 2012 · 0 comments

Comments

Projects
None yet
2 participants
Contributor

bfroehle commented Sep 18, 2012

Magic functions with docstrings produced by magic_arguments all have the following form:

%magic [usage]

<description, as taken from __doc__>

optional arguments:
    <...>
required arguments:
    <...>

This, however, is not ideal as:

  1. Often we would like examples to appear after the list of arguments and their functions.
  2. The first line should be a short description.

The first issue could be solved in a hacky way:

@magic_arguments.kwds(epilog=dedent(""" .... examples and such ..."""))

But the second line cannot be solved at all.

The most elegant way to solve this might be to interpret the docstring as a template and use named substitution parameters to insert the usage help. For example:

@magic_arguments.magic_arguments()
...
def script(self, line, cell):
    """
    Run a cell via a shell command

    The `%%script` line is like the #! line of script,
    specifying a program (bash, perl, ruby, etc.) with which to run.

    The rest of the cell is run by that program.

    %(help)s

    Examples
    --------
    ::

        In [1]: %%script bash
           ...: for i in 1 2 3; do
           ...:   echo $i
           ...: done
        1
        2
        3
    """

could produce

Run a cell via a shell command

The `%%script` line is like the #! line of script,
specifying a program (bash, perl, ruby, etc.) with which to run.

The rest of the cell is run by that program.

usage : %shebang [--proc PROC] [--bg] [--err ERR] [--out OUT]

optional arguments:
  --proc PROC  The variable in which to store Popen instance. This is used
               only when --bg option is given.
  --bg         Whether to run the script in the background. If given, the only
               way to see the output of the command is with --out/err.
  --err ERR    The variable in which to store stderr from the script. If the
               script is backgrounded, this will be the stderr *pipe*, instead
               of the stderr text itself.
  --out OUT    The variable in which to store stdout from the script. If the
               script is backgrounded, this will be the stdout *pipe*, instead
               of the stderr text itself.

Examples
--------
::

    In [1]: %%script bash
       ...: for i in 1 2 3; do
       ...:   echo $i
       ...: done
    1
    2
    3

Thoughts?

minrk removed the type-enhancement label Jan 14, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment