render the example in numpydoc, add ifconfig for host python major version

2 files changed, 26 insertions, 2 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1cd57697d..9e1d1a142 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,7 +22,7 @@ sys.path.insert(0, os.path.abspath('../sphinxext'))
 extensions = ['sphinx.ext.autodoc', 'numpydoc',
               'sphinx.ext.intersphinx', 'sphinx.ext.coverage',
               'sphinx.ext.doctest', 'sphinx.ext.autosummary',
-              'sphinx.ext.graphviz',
+              'sphinx.ext.graphviz', 'sphinx.ext.ifconfig',
               'matplotlib.sphinxext.plot_directive']
 
 if sphinx.__version__ >= "1.4":
@@ -82,6 +82,9 @@ add_function_parentheses = False
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+def setup(app):
+    # add a config value for `ifconfig` directives
+    app.add_config_value('python_version_major', str(sys.version_info.major), 'env')
 
 # -----------------------------------------------------------------------------
 # HTML output
diff --git a/doc/source/docs/howto_document.rst b/doc/source/docs/howto_document.rst
index 35fe95fa4..de7d06cf8 100644
--- a/doc/source/docs/howto_document.rst
+++ b/doc/source/docs/howto_document.rst
@@ -33,8 +33,29 @@ after which you may use it::
 
   np.fft.fft2(...)
 
-.. rubric:: **For convenience the** `formatting standard`_ **is included below.**
+.. rubric::
+    **For convenience the** `formatting standard`_ **is included below with an
+    example**
 
 .. include:: ../../sphinxext/doc/format.rst
 
+.. _example:
+
+Example Source
+==============
+
+.. literalinclude:: ../../sphinxext/doc/example.py
+
+
+
+Example Rendered
+================
+
+.. ifconfig:: python_version_major < '3'
+
+    The example is rendered only when sphinx is run with python3 and above
+
+.. automodule:: doc.example
+    :members:
+
 .. _`formatting standard`: https://numpydoc.readthedocs.io/en/latest/format.html