autogen_magics.py
66 lines
| 2.0 KiB
| text/x-python
|
PythonLexer
/ docs / autogen_magics.py
digitalvirtuoso
|
r26056 | from pathlib import Path | ||
Thomas Kluyver
|
r18294 | from IPython.core.alias import Alias | ||
from IPython.core.interactiveshell import InteractiveShell | ||||
Thomas Kluyver
|
r18317 | from IPython.core.magic import MagicAlias | ||
Thomas Kluyver
|
r18294 | from IPython.utils.text import dedent, indent | ||
shell = InteractiveShell.instance() | ||||
Thomas Kluyver
|
r18317 | magics = shell.magics_manager.magics | ||
Thomas Kluyver
|
r18294 | |||
Thomas Kluyver
|
r18296 | def _strip_underline(line): | ||
chars = set(line.strip()) | ||||
Adam Hackbarth
|
r26070 | if len(chars) == 1 and ("-" in chars or "=" in chars): | ||
Thomas Kluyver
|
r18296 | return "" | ||
else: | ||||
return line | ||||
Thomas Kluyver
|
r18317 | def format_docstring(func): | ||
docstring = (func.__doc__ or "Undocumented").rstrip() | ||||
Thomas Kluyver
|
r18296 | docstring = indent(dedent(docstring)) | ||
# Sphinx complains if indented bits have rst headings in, so strip out | ||||
# any underlines in the docstring. | ||||
lines = [_strip_underline(l) for l in docstring.splitlines()] | ||||
return "\n".join(lines) | ||||
Thomas Kluyver
|
r18294 | output = [ | ||
"Line magics", | ||||
"===========", | ||||
"", | ||||
] | ||||
Thomas Kluyver
|
r18296 | # Case insensitive sort by name | ||
def sortkey(s): return s[0].lower() | ||||
Adam Hackbarth
|
r26070 | for name, func in sorted(magics["line"].items(), key=sortkey): | ||
Thomas Kluyver
|
r18317 | if isinstance(func, Alias) or isinstance(func, MagicAlias): | ||
Thomas Kluyver
|
r18294 | # Aliases are magics, but shouldn't be documented here | ||
Thomas Kluyver
|
r18317 | # Also skip aliases to other magics | ||
Thomas Kluyver
|
r18294 | continue | ||
Thomas Kluyver
|
r18296 | output.extend([".. magic:: {}".format(name), | ||
Thomas Kluyver
|
r18294 | "", | ||
Thomas Kluyver
|
r18317 | format_docstring(func), | ||
Thomas Kluyver
|
r18294 | ""]) | ||
output.extend([ | ||||
Thomas Kluyver
|
r18296 | "Cell magics", | ||
"===========", | ||||
Thomas Kluyver
|
r18294 | "", | ||
]) | ||||
Adam Hackbarth
|
r26070 | for name, func in sorted(magics["cell"].items(), key=sortkey): | ||
Thomas Kluyver
|
r18296 | if name == "!": | ||
# Special case - don't encourage people to use %%! | ||||
continue | ||||
Adam Hackbarth
|
r26070 | if func == magics["line"].get(name, "QQQP"): | ||
Thomas Kluyver
|
r18294 | # Don't redocument line magics that double as cell magics | ||
continue | ||||
Thomas Kluyver
|
r18317 | if isinstance(func, MagicAlias): | ||
continue | ||||
Thomas Kluyver
|
r18296 | output.extend([".. cellmagic:: {}".format(name), | ||
Thomas Kluyver
|
r18294 | "", | ||
Thomas Kluyver
|
r18317 | format_docstring(func), | ||
Thomas Kluyver
|
r18294 | ""]) | ||
digitalvirtuoso
|
r26056 | src_path = Path(__file__).parent | ||
Adam Hackbarth
|
r26070 | dest = src_path.joinpath("source", "interactive", "magics-generated.txt") | ||
gousaiyang
|
r27495 | dest.write_text("\n".join(output), encoding="utf-8") | ||