##// END OF EJS Templates
back to dev
back to dev

File last commit:

r27495:1a9d9554
r29041:cc014ab7 8.x
Show More
autogen_magics.py
66 lines | 2.0 KiB | text/x-python | PythonLexer
/ docs / autogen_magics.py
digitalvirtuoso
Updated to Pathlib Path from os
r26056 from pathlib import Path
Thomas Kluyver
Generate documentation of line & cell magics
r18294 from IPython.core.alias import Alias
from IPython.core.interactiveshell import InteractiveShell
Thomas Kluyver
Skip documenting aliases to other magic commands
r18317 from IPython.core.magic import MagicAlias
Thomas Kluyver
Generate documentation of line & cell magics
r18294 from IPython.utils.text import dedent, indent
shell = InteractiveShell.instance()
Thomas Kluyver
Skip documenting aliases to other magic commands
r18317 magics = shell.magics_manager.magics
Thomas Kluyver
Generate documentation of line & cell magics
r18294
Thomas Kluyver
Various improvements to docs infrastructure for magics
r18296 def _strip_underline(line):
chars = set(line.strip())
Adam Hackbarth
Updated Text Quote formatting
r26070 if len(chars) == 1 and ("-" in chars or "=" in chars):
Thomas Kluyver
Various improvements to docs infrastructure for magics
r18296 return ""
else:
return line
Thomas Kluyver
Skip documenting aliases to other magic commands
r18317 def format_docstring(func):
docstring = (func.__doc__ or "Undocumented").rstrip()
Thomas Kluyver
Various improvements to docs infrastructure for magics
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
Generate documentation of line & cell magics
r18294 output = [
"Line magics",
"===========",
"",
]
Thomas Kluyver
Various improvements to docs infrastructure for magics
r18296 # Case insensitive sort by name
def sortkey(s): return s[0].lower()
Adam Hackbarth
Updated Text Quote formatting
r26070 for name, func in sorted(magics["line"].items(), key=sortkey):
Thomas Kluyver
Skip documenting aliases to other magic commands
r18317 if isinstance(func, Alias) or isinstance(func, MagicAlias):
Thomas Kluyver
Generate documentation of line & cell magics
r18294 # Aliases are magics, but shouldn't be documented here
Thomas Kluyver
Skip documenting aliases to other magic commands
r18317 # Also skip aliases to other magics
Thomas Kluyver
Generate documentation of line & cell magics
r18294 continue
Thomas Kluyver
Various improvements to docs infrastructure for magics
r18296 output.extend([".. magic:: {}".format(name),
Thomas Kluyver
Generate documentation of line & cell magics
r18294 "",
Thomas Kluyver
Skip documenting aliases to other magic commands
r18317 format_docstring(func),
Thomas Kluyver
Generate documentation of line & cell magics
r18294 ""])
output.extend([
Thomas Kluyver
Various improvements to docs infrastructure for magics
r18296 "Cell magics",
"===========",
Thomas Kluyver
Generate documentation of line & cell magics
r18294 "",
])
Adam Hackbarth
Updated Text Quote formatting
r26070 for name, func in sorted(magics["cell"].items(), key=sortkey):
Thomas Kluyver
Various improvements to docs infrastructure for magics
r18296 if name == "!":
# Special case - don't encourage people to use %%!
continue
Adam Hackbarth
Updated Text Quote formatting
r26070 if func == magics["line"].get(name, "QQQP"):
Thomas Kluyver
Generate documentation of line & cell magics
r18294 # Don't redocument line magics that double as cell magics
continue
Thomas Kluyver
Skip documenting aliases to other magic commands
r18317 if isinstance(func, MagicAlias):
continue
Thomas Kluyver
Various improvements to docs infrastructure for magics
r18296 output.extend([".. cellmagic:: {}".format(name),
Thomas Kluyver
Generate documentation of line & cell magics
r18294 "",
Thomas Kluyver
Skip documenting aliases to other magic commands
r18317 format_docstring(func),
Thomas Kluyver
Generate documentation of line & cell magics
r18294 ""])
digitalvirtuoso
Updated to Pathlib Path from os
r26056 src_path = Path(__file__).parent
Adam Hackbarth
Updated Text Quote formatting
r26070 dest = src_path.joinpath("source", "interactive", "magics-generated.txt")
gousaiyang
Format code
r27495 dest.write_text("\n".join(output), encoding="utf-8")