Improve docs; replace TestFailure and hexdiffs usage

docs/source/conf.py

@@ -48,10 +48,10 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "cocotb": ("https://docs.cocotb.org/en/latest/", None),
     "ghdl": ("https://ghdl.github.io/ghdl", None),
     "scapy": ("https://scapy.readthedocs.io/en/latest", None),
     "pytest": ("https://docs.pytest.org/en/latest/", None),
-    #"cocotb": ("https://docs.cocotb.org/en/latest/", None),
 }
 
 # Github repo
@@ -71,7 +71,7 @@
 
 # General information about the project.
 project = "cocotb-bus"
-copyright = "2014-{0}, cocotb contributors".format(datetime.datetime.now().year)
+copyright = "2014-{0}, cocotb-bus contributors".format(datetime.datetime.now().year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/source/index.rst

@@ -15,11 +15,14 @@ Welcome to cocotb-bus's documentation!
 What is cocotb-bus?
 *******************
 
-**cocotb-bus** is:
+**cocotb-bus** consists of pre-packaged testbenching tools and reusable bus interfaces
+for https://cocotb.org.
 
-* A set of Driver's & Monitor base classes to assist in creating cocotb VIP's.
-* An implementation of scoreboard class for cocotb.
-* Sample implementation of Protocol Bus drivers using these classes.
+A bit more detailed, cocotb-bus is:
+
+* A set of Driver & Monitor base classes to assist in creating cocotb VIPs.
+* An implementation of a scoreboard class for cocotb.
+* Sample implementation of protocol bus drivers using these classes.
 
 
 .. toctree::
@@ -44,13 +47,13 @@ What is cocotb-bus?
    - no distractions
 
 ..
-.. toctree::
-   :maxdepth: 1
-   :caption: Tutorials
-   :name: tutorials
-   :hidden:
+   .. toctree::
+      :maxdepth: 1
+      :caption: Tutorials
+      :name: tutorials
+      :hidden:
 
-   examples
+      examples
 
 
 ..
@@ -66,18 +69,18 @@ What is cocotb-bus?
    - good naming
 
 ..
-.. toctree::
-   :maxdepth: 1
-   :caption: How-to Guides
-   :name: howto_guides
-   :hidden:
-
-   writing_testbenches
-   runner
-   coroutines
-   triggers
-   custom_flows
-   rotating_logger
+   .. toctree::
+      :maxdepth: 1
+      :caption: How-to Guides
+      :name: howto_guides
+      :hidden:
+
+      writing_testbenches
+      runner
+      coroutines
+      triggers
+      custom_flows
+      rotating_logger
 
 .. todo::
    - Howto use the baseclasses to create VIP
@@ -95,14 +98,14 @@ What is cocotb-bus?
    - no instruction or technical description
 
 ..
-.. toctree::
-   :maxdepth: 1
-   :caption: Key topics
-   :name: key_topics
-   :hidden:
+   .. toctree::
+      :maxdepth: 1
+      :caption: Key topics
+      :name: key_topics
+      :hidden:
 
-   install_devel
-   troubleshooting
+      install_devel
+      troubleshooting
 
 
 
@@ -124,18 +127,18 @@ What is cocotb-bus?
 
    Python Code Library Reference <library_reference>
 
-..
 .. toctree::
    :maxdepth: 1
    :caption: Development & Community
    :name: development_community
    :hidden:
 
-   roadmap
-   contributors
    release_notes
-   further_resources
 ..
+      roadmap
+      contributors
+      further_resources
+
 .. todo::
    - Add "Join us online" and "Contributing"
    - In Contributing, add explanation on how to provide a PR, how to test existing PRs, etc.
@@ -148,5 +151,6 @@ What is cocotb-bus?
    :hidden:
 
    Classes, Methods, Variables etc. <genindex>
-   Python Modules <py-modindex>
    glossary
+..
+   Python Modules <py-modindex>

docs/source/library_reference.rst

@@ -2,7 +2,7 @@
 Library Reference
 *****************
 
-.. spelling::
+.. spelling:word-list::
    AXIProtocolError
    BusDriver
    De
@@ -74,3 +74,107 @@ Scoreboard
     :show-inheritance:
     :synopsis: Class for scoreboards.
 
+
+Implemented Testbench Structures
+================================
+
+Drivers
+-------
+
+AMBA
+^^^^
+
+Advanced Microcontroller Bus Architecture.
+
+.. currentmodule:: cocotb_bus.drivers.amba
+
+.. autoclass:: AXI4Master
+    :members:
+    :member-order: bysource
+
+.. autoclass:: AXI4LiteMaster
+    :members:
+    :member-order: bysource
+
+.. autoclass:: AXI4Slave
+    :members:
+    :member-order: bysource
+
+
+Avalon
+^^^^^^
+
+.. currentmodule:: cocotb_bus.drivers.avalon
+
+.. autoclass:: AvalonMM
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+
+.. autoclass:: AvalonMaster
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+
+.. autoclass:: AvalonMemory
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+
+.. autoclass:: AvalonST
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+
+.. autoclass:: AvalonSTPkts
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+
+
+OPB
+^^^
+
+.. currentmodule:: cocotb_bus.drivers.opb
+
+.. autoclass:: OPBMaster
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+
+
+XGMII
+^^^^^
+
+.. currentmodule:: cocotb_bus.drivers.xgmii
+
+.. autoclass:: XGMII
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+
+Monitors
+--------
+
+Avalon
+^^^^^^
+
+.. currentmodule:: cocotb_bus.monitors.avalon
+
+.. autoclass:: AvalonST
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+
+.. autoclass:: AvalonSTPkts
+    :members:
+    :member-order: bysource
+    :show-inheritance:
+
+XGMII
+^^^^^
+
+.. autoclass:: cocotb_bus.monitors.xgmii.XGMII
+    :members:
+    :member-order: bysource
+    :show-inheritance: