Merge pull request #12886 from MrMino/reformat_cd_magic_docs

Reformat and improve the wording of %cd docstring

IPython/core/magics/osm.py

@@ -302,33 +302,36 b' class OSMagics(Magics):'
         """Change the current working directory.
 
         This command automatically maintains an internal list of directories
-        you visit during your IPython session, in the variable _dh. The
-        command %dhist shows this history nicely formatted. You can also
-        do 'cd -<tab>' to see directory history conveniently.
-
+        you visit during your IPython session, in the variable ``_dh``. The
+        command :magic:`%dhist` shows this history nicely formatted. You can
+        also do ``cd -<tab>`` to see directory history conveniently.
         Usage:
 
-          cd 'dir': changes to directory 'dir'.
-
-          cd -: changes to the last visited directory.
+          - ``cd 'dir'``: changes to directory 'dir'.
+          - ``cd -``: changes to the last visited directory.
+          - ``cd -<n>``: changes to the n-th directory in the directory history.
+          - ``cd --foo``: change to directory that matches 'foo' in history
+          - ``cd -b <bookmark_name>``: jump to a bookmark set by %bookmark
+          - Hitting a tab key after ``cd -b`` allows you to tab-complete
+            bookmark names.
 
-          cd -<n>: changes to the n-th directory in the directory history.
+          .. note::
+            ``cd <bookmark_name>`` is enough if there is no directory
+            ``<bookmark_name>``, but a bookmark with the name exists.
 
-          cd --foo: change to directory that matches 'foo' in history
-
-          cd -b <bookmark_name>: jump to a bookmark set by %bookmark
-             (note: cd <bookmark_name> is enough if there is no
-              directory <bookmark_name>, but a bookmark with the name exists.)
-              'cd -b <tab>' allows you to tab-complete bookmark names.
 
         Options:
 
-        -q: quiet.  Do not print the working directory after the cd command is
-        executed.  By default IPython's cd command does print this directory,
-        since the default prompts do not display path information.
+        -q               Be quiet. Do not print the working directory after the
+                         cd command is executed. By default IPython's cd
+                         command does print this directory, since the default
+                         prompts do not display path information.
+
+        .. note::
+           Note that ``!cd`` doesn't work for this purpose because the shell
+           where ``!command`` runs is immediately discarded after executing
+           'command'.
 
-        Note that !cd doesn't work for this purpose because the shell where
-        !command runs is immediately discarded after executing 'command'.
 
         Examples
         --------