ipython/ipython — pull request #6679 by takluyver (2014-10-10 22:38:18+00:00)
Title: Proper documentation for magics

This is something that's been annoying me for a while: the only documentation of magic commands is the API documentation of the methods that they refer to. This isn't obvious to find, is hard to cross reference, and I don't consider those methods to be in any way part of our public API.

This adds automatically generated documentation of our built in magics. They're properly integrated, so they can be referenced by URL, they show up in the index, and you can easily cross reference them using roles like:

```rst
:magic:`run`
:cellmagic:`writefile`
```

It also excludes `IPython.core.magics` from the API documentation, since that's not public API.

Decisions:

1. What to do with things that are both a line and cell magic? For now, I've documented them as line magics, and relied on their docstring to describe their use as a cell magic. This means that a cross-reference to e.g. timeit must use `:magic:`, not `:cellmagic:`.
2. Aliases - do we include them or not? e.g. `%hist` and `%history`, `%%HTML` and `%%html`.