Merge pull request #5040 from takluyver/docs-extensions-polish

Polishing some docs

docs/source/config/extensions/index.rst

@@ -7,7 +7,7 @@ IPython extensions
 A level above configuration are IPython extensions, Python modules which modify
 the behaviour of the shell. They are referred to by an importable module name,
 and can be placed anywhere you'd normally import from, or in
-``$IPYTHONDIR/extensions/``.
+``.ipython/extensions/``.
 
 Getting extensions
 ==================
@@ -61,11 +61,15 @@ Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiv
 :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and 
 :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading).
 
+.. seealso::
+
+   :ref:`defining_magics`
+
 You can put your extension modules anywhere you want, as long as they can be
 imported by Python's standard import mechanism. However, to make it easy to
-write extensions, you can also put your extensions in
-``os.path.join(ip.ipython_dir, 'extensions')``. This directory is added to
-``sys.path`` automatically.
+write extensions, you can also put your extensions in :file:`extensions/`
+within the :ref:`IPython directory <ipythondir>`. This directory is
+added to :data:`sys.path` automatically.
 
 When your extension is ready for general use, please add it to the `extensions
 index <https://github.com/ipython/ipython/wiki/Extensions-Index>`_.

docs/source/interactive/reference.rst

@@ -11,10 +11,6 @@ You start IPython with the command::
 
     $ ipython [options] files
 
-.. note::
-
-  For IPython on Python 3, use ``ipython3`` in place of ``ipython``.
-
 If invoked with no options, it executes all the files listed in sequence
 and drops you into the interpreter while still acknowledging any options
 you may have set in your ipython_config.py. This behavior is different from
@@ -24,12 +20,11 @@ file and ignore your configuration setup.
 Please note that some of the configuration options are not available at
 the command line, simply because they are not practical here. Look into
 your configuration files for details on those. There are separate configuration 
-files for each profile, and the files look like "ipython_config.py" or 
-"ipython_config_<frontendname>.py".  Profile directories look like 
-"profile_profilename" and are typically installed in the IPYTHONDIR directory,
+files for each profile, and the files look like :file:`ipython_config.py` or
+:file:`ipython_config_{frontendname}.py`.  Profile directories look like
+:file:`profile_{profilename}` and are typically installed in the :envvar:`IPYTHONDIR` directory,
 which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME`
-resolves to :file:`C:\\Documents and Settings\\YourUserName` in most
-instances.
+resolves to :file:`C:\\Users\\{YourUserName}` in most instances.
 
 
 Eventloop integration
@@ -165,6 +160,8 @@ An example (with automagic on) should clarify all this:
 
     /home/fperez/ipython
 
+.. _defining_magics:
+
 Defining your own magics
 ++++++++++++++++++++++++