From 610453415047ccb597156bdf6bfa9c0887257fa3 Mon Sep 17 00:00:00 2001
From: Jan Decaluwe <jan@jandecaluwe.com>
Date: Sun, 1 Apr 2018 10:29:07 +0200
Subject: [PATCH] reference update for block

---
 doc/source/manual/reference.rst | 69 ++++++++++++++++++++++++++++++++-
 doc/source/myhdldoctools.py     |  4 +-
 2 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/doc/source/manual/reference.rst b/doc/source/manual/reference.rst
index 53ef0163..7b0a35ab 100644
--- a/doc/source/manual/reference.rst
+++ b/doc/source/manual/reference.rst
@@ -115,6 +115,71 @@ Waveform tracing
 Modeling
 ========
 
+.. _ref-block:
+
+The `block` decorator
+---------------------
+
+.. function:: block()
+
+   The `block` decorator enables a method-based API which is more consistent,
+   simplifies implementation, and reduces the size of the `myhdl` namespace.
+    
+   The methods work on block instances, created by calling a function decorated
+   with the `block` decorator::
+
+       @block
+       def myblock(<ports>):
+       ...
+       return <instances>
+       
+       inst = myblock(<port-associations>)
+       # inst supports the methods of the block instance API
+
+The API on a block instance looks as follows:
+
+.. method:: <block_instance>.run_sim(duration=None)
+
+   Run a simulation "forever" (default) or for a specified duration.   
+
+.. method:: <block_instance>.config_sim(backend='myhdl', trace=False)
+
+   Optional simulation configuration: 
+
+   *backend*: Defaults to 'myhdl
+
+   *trace*: Enable waveform tracing, default False.  
+
+.. method:: <block_instance>.quit_sim()
+
+   Quit an active simulation. This is method is currently required because
+   only a single simulation can be active.
+
+.. method:: <block_instance>.convert(hdl='Verilog', **kwargs)  
+
+   Converts MyHDL code to a target HDL.
+
+   *hdl*:'VHDL' or 'Verilog'. Defaults to Verilog.
+
+   Supported keyword arguments:
+
+   *path*: Destination folder. Defaults to current working dir.   
+
+   *name*: Module and output file name. Defaults to `self.mod.__name__`.      
+
+   *trace*: Whether the testbench should dump all signal waveforms. Defaults to False.   
+
+   *testbench*: Verilog only. Specifies whether a testbench should be created.  Defaults to True.   
+
+   *timescale*: timescale parameter. Defaults to '1ns/10ps'. Verilog only.   
+
+.. method:: <block_instance>.verify_convert()
+
+  Verify conversion output, by comparing target HDL simulation log with MyHDL simulation log.   
+
+.. method:: <block_instance>.analyze_convert()
+
+  Analyze conversion output by compilation with target HDL compiler.   
 
 .. _ref-sig:
 
@@ -346,8 +411,8 @@ are forked, while the original generator resumes immediately.
 
 .. _ref-deco:
 
-Decorator functions
--------------------
+Decorator functions to create generators
+----------------------------------------
 
 MyHDL defines a number of decorator functions, that make it easier to create
 generators from local generator functions.
diff --git a/doc/source/myhdldoctools.py b/doc/source/myhdldoctools.py
index cf57e98d..85ab6427 100644
--- a/doc/source/myhdldoctools.py
+++ b/doc/source/myhdldoctools.py
@@ -2,7 +2,9 @@ import subprocess
 
 from docutils import nodes
 
-from sphinx.util.compat import Directive
+# deprecated
+# from sphinx.util.compat import Directive
+from docutils.parsers.rst import Directive
 from sphinx.directives.code import LiteralInclude
 
 example_dir = '/../../example/manual/'