From 5afbf7163a22ec6be0ec4ea7c5713d1f336b18be 2020-10-02 01:25:35
From: farisachugthai <farischugthai@gmail.com>
Date: 2020-10-02 01:25:35
Subject: [PATCH] DOC: Define ipy directive as such in docs.

By utilizing the directive `rst:directive::`, one can now link to the
documentation on the sphinx directive using an inline reference as well
as now being able to link to any of the options.

Put this early in the documentation as it's useful to quickly summarize
the options and decorators available to the user immediately.

The currently provided examples are phenomenal but having a thorough
reference and all of the options in one place and having them be easy to
create a hyperlink to is also very important.

---

diff --git a/docs/source/sphinxext.rst b/docs/source/sphinxext.rst
index 5b4371e..a381814 100644
--- a/docs/source/sphinxext.rst
+++ b/docs/source/sphinxext.rst
@@ -10,12 +10,15 @@ IPython Sphinx Directive
    The IPython Sphinx Directive is in 'beta' and currently under
    active development. Improvements to the code or documentation are welcome!
 
-The ipython directive is a stateful ipython shell for embedding in
-sphinx documents.  It knows about standard ipython prompts, and
-extracts the input and output lines.  These prompts will be renumbered
-starting at ``1``.  The inputs will be fed to an embedded ipython
-interpreter and the outputs from that interpreter will be inserted as
-well.  For example, code blocks like the following::
+.. |rst| replace:: reStructured text
+
+The :rst:dir:`ipython` directive is a stateful shell that can be used
+in |rst| files.
+
+It knows about standard ipython prompts, and extracts the input and output
+lines.  These prompts will be renumbered starting at ``1``.  The inputs will be
+fed to an embedded ipython interpreter and the outputs from that interpreter
+will be inserted as well.  For example, code blocks like the following::
 
   .. ipython::
 
@@ -42,6 +45,48 @@ will be rendered as
    document that generates the rendered output.
 
 
+Directive and options
+=====================
+
+The IPython directive takes a number of options detailed here.
+
+.. rst:directive:: ipython
+
+   Create an IPython directive.
+
+   .. rst:directive:option:: doctest
+
+      Run a doctest on IPython code blocks in rst.
+
+   .. rst:directive:option:: python
+
+      Used to indicate that the relevant code block does not have IPython prompts.
+
+   .. rst:directive:option:: okexcept
+
+      Allow the code block to raise an exception.
+
+   .. rst:directive:option:: okwarning
+
+      Allow the code block to emit an warning.
+
+   .. rst:directive:option:: suppress
+
+      Silence any warnings or expected errors.
+
+   .. rst:directive:option:: verbatim
+
+      A noop that allows for any text to be syntax highlighted as valid IPython code.
+
+   .. rst:directive:option:: savefig: OUTFILE [IMAGE_OPTIONS]
+
+      Save output from matplotlib to *outfile*.
+
+It's important to note that all of these options can be used for the entire
+directive block or they can decorate individual lines of code as explained
+in :ref:`pseudo-decorators`.
+
+
 Persisting the Python session across IPython directive blocks
 =============================================================
 
@@ -393,6 +438,8 @@ Pretty much anything you can do with the ipython code, you can do with
 with a simple python script. Obviously, though it doesn't make sense
 to use the doctest option.
 
+.. _pseudo-decorators:
+
 Pseudo-Decorators
 =================