docs: custom directive for including/running examples

doc/source/conf.py

@@ -18,6 +18,7 @@ import sys, os
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../..'))
+sys.path.append(os.path.abspath('.'))
 import myhdl
 
 # -- General configuration -----------------------------------------------------
@@ -28,7 +29,8 @@ import myhdl
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.intersphinx',
-              'sphinx.ext.doctest']
+              'sphinx.ext.doctest',
+              'myhdldoctools']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/source/manual/intro.rst

@@ -14,32 +14,13 @@ A basic MyHDL simulation
 We will introduce MyHDL with a classic ``Hello World`` style example. All
 example code can be found in the distribution directory under
 :file:`example/manual/`.  Here are the contents of a MyHDL simulation script
-called :file:`hello1.py`::
+called :file:`hello1.py`:
 
-   from myhdl import Signal, delay, always, now, Simulation
+.. include-example:: hello1.py
 
-   def HelloWorld():
+When we run this simulation, we get the following output:
 
-       interval = delay(10)
+.. run-example:: hello1.py
-
-       @always(interval)
-       def sayHello():
-           print "%s Hello World!" % now()
-
-       return sayHello
-
-
-   inst = HelloWorld()
-   sim = Simulation(inst)
-   sim.run(30)
-
-When we run this simulation, we get the following output::
-
-   % python hello1.py
-   10 Hello World!
-   20 Hello World!
-   30 Hello World!
-   _SuspendSimulation: Simulated 30 timesteps
 
 The first line of the script imports a number of objects from the ``myhdl``
 package. In Python we can only use identifiers that are literally defined in the

doc/source/myhdldoctools.py

@@ -0,0 +1,35 @@
+import subprocess
+
+from docutils import nodes
+
+from sphinx.util.compat import Directive
+from sphinx.directives.code import LiteralInclude
+
+example_dir = '/../../example/manual/'
+
+class IncludeExample(LiteralInclude):
+    def run(self):
+        self.arguments[0] = '{}/{}'.format(example_dir, self.arguments[0])
+        return super(IncludeExample, self).run()
+
+class RunExample(Directive):
+    has_content = False
+    required_arguments = 1
+    final_argument_whitespace = True
+
+    def run(self):
+        document = self.state.document
+        env = document.settings.env
+        _ , wd = env.relfn2path(example_dir)
+        prog = self.arguments[0]
+        out = subprocess.check_output(['python', '-u', prog], cwd=wd, 
+                                      stderr=subprocess.STDOUT,
+                                      universal_newlines=True)
+        out = '$ python {}\n{}'.format(prog, out)
+        ret = [nodes.literal_block(out, out)]
+        return ret
+
+
+def setup(app):
+    app.add_directive('include-example', IncludeExample)
+    app.add_directive('run-example', RunExample)