Hello,
migen so far has excellent tutorial-style documentation from Sebastien
but there should also be API documentation for the individual modules.
If the numpydoc format is used for docstrings, the API documentation
can be generated quickly. These patches get the API documentation
started but obviusly there are still a lot of docstrings to be
written.
Examples/doctests could also be included in the docstrings but
unfortunately the amount of required boilerplate code (basically a
testbench) is large.
--
Robert Jordens.
From c0d6171e0fac8a1b7caabda8062767c7cf97ad71 Mon Sep 17 00:00:00 2001
From: Robert Jordens <jord...@gmail.com>
Date: Thu, 28 Nov 2013 01:46:08 -0700
Subject: [PATCH 1/2] add autodoc, numpydoc and doctest to sphinx to generate
API doc
---
doc/conf.py | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/doc/conf.py b/doc/conf.py
index 270e050..601e717 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -25,7 +25,13 @@ import sys, os
# 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.pngmath']
+extensions = [
+ 'sphinx.ext.pngmath',
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.doctest',
+ 'sphinx.ext.autosummary',
+ 'numpydoc', # to preprocess docstrings
+ ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
--
1.8.3.2
From 51de5ba02a5db8c266ddad029319cc8d4302172c Mon Sep 17 00:00:00 2001
From: Robert Jordens <jord...@gmail.com>
Date: Thu, 28 Nov 2013 01:46:52 -0700
Subject: [PATCH 2/2] setup API documentation, start by documenting fifos
---
doc/api.rst | 8 ++++++++
doc/index.rst | 1 +
migen/genlib/fifo.py | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 59 insertions(+)
create mode 100644 doc/api.rst
diff --git a/doc/api.rst b/doc/api.rst
new file mode 100644
index 0000000..06f2330
--- /dev/null
+++ b/doc/api.rst
@@ -0,0 +1,8 @@
+migen Package
+=============
+
+:mod:`genlib.fifo` Module
+------------------------------
+
+.. automodule:: migen.genlib.fifo
+ :members:
diff --git a/doc/index.rst b/doc/index.rst
index 6f3644d..6c21d76 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -10,3 +10,4 @@ Migen manual
dataflow
simulation
casestudies
+ api
diff --git a/migen/genlib/fifo.py b/migen/genlib/fifo.py
index afb397f..0e4ce54 100644
--- a/migen/genlib/fifo.py
+++ b/migen/genlib/fifo.py
@@ -13,6 +13,37 @@ def _inc(signal, modulo):
)
class _FIFOInterface:
+ """
+ Data written to the input interface (`din`, `we`, `writable`) is
+ buffered and can be read at the output interface (`dout`, `re`,
+ `readable`). The data entry written first to the input
+ also appears first on the output.
+
+ Parameters
+ ==========
+ width_or_layout : int, layout
+ Bit width or `Record` layout for the data.
+ depth : int
+ Depth of the FIFO.
+
+ Attributes
+ ==========
+ din : in, width_or_layout
+ Input data either flat or Record structured.
+ writable : out
+ There is space in the FIFO and `we` can be asserted.
+ we : in
+ Write enable signal to latch `din` into the FIFO. Only assert if
+ `writable` is asserted.
+ dout : out, width_or_layout
+ Output data, same type as `din`. Only valid if `readable` is
+ asserted.
+ readable : out
+ Output data `dout` valid, FIFO not empty.
+ re : in
+ Acknowledge `dout`. If asserted, the next entry will be
+ available on the next cycle (if `readable` is high then).
+ """
def __init__(self, width_or_layout, depth):
self.we = Signal()
self.writable = Signal() # not full
@@ -33,6 +64,15 @@ class _FIFOInterface:
self.width = width_or_layout
class SyncFIFO(Module, _FIFOInterface):
+ """Synchronous FIFO (first in, first out)
+
+ Read and write interfaces are accessed from the same clock domain.
+ If different clock domains are needed, use :class:`AsyncFIFO`.
+
+ {interface}
+ """
+ __doc__ = __doc__.format(interface=_FIFOInterface.__doc__)
+
def __init__(self, width_or_layout, depth):
_FIFOInterface.__init__(self, width_or_layout, depth)
@@ -81,6 +121,16 @@ class SyncFIFO(Module, _FIFOInterface):
]
class AsyncFIFO(Module, _FIFOInterface):
+ """Asynchronous FIFO (first in, first out)
+
+ Read and write interfaces are accessed from different clock domains,
+ named `read` and `write`. Use `RenameClockDomains` to rename to
+ other names.
+
+ {interface}
+ """
+ __doc__ = __doc__.format(interface=_FIFOInterface.__doc__)
+
def __init__(self, width_or_layout, depth):
_FIFOInterface.__init__(self, width_or_layout, depth)
--
1.8.3.2
_______________________________________________
Devel mailing list
Devel@lists.milkymist.org
https://ssl.serverraum.org/lists/listinfo/devel
