From 728b60d2f565d13adb028603e2d3126eaa984ea8 Mon Sep 17 00:00:00 2001 From: Catherine Date: Mon, 13 Dec 2021 05:48:31 +0000 Subject: [PATCH] docs: cover `nmigen.lib.coding`. --- docs/conf.py | 6 ++++++ docs/index.rst | 1 + docs/stdlib.rst | 11 +++++++++++ docs/stdlib/coding.rst | 27 +++++++++++++++++++++++++++ nmigen/lib/coding.py | 12 +++++------- 5 files changed, 50 insertions(+), 7 deletions(-) create mode 100644 docs/stdlib.rst create mode 100644 docs/stdlib/coding.rst diff --git a/docs/conf.py b/docs/conf.py index 22ab5cd..234fcb8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,6 +12,8 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx.ext.doctest", "sphinx.ext.todo", + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", "sphinx_rtd_theme", "sphinxcontrib.platformpicker", ] @@ -25,6 +27,10 @@ intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} todo_include_todos = True +napoleon_google_docstring = False +napoleon_numpy_docstring = True +napoleon_use_ivar = True + html_theme = "sphinx_rtd_theme" html_static_path = ["_static"] html_css_files = ["custom.css"] diff --git a/docs/index.rst b/docs/index.rst index cade289..97a51ca 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,3 +13,4 @@ Language & toolchain start tutorial lang + stdlib diff --git a/docs/stdlib.rst b/docs/stdlib.rst new file mode 100644 index 0000000..333db16 --- /dev/null +++ b/docs/stdlib.rst @@ -0,0 +1,11 @@ +Standard library +################ + +.. todo:: + + Write this section. + +.. toctree:: + :maxdepth: 2 + + stdlib/coding diff --git a/docs/stdlib/coding.rst b/docs/stdlib/coding.rst new file mode 100644 index 0000000..1f1732f --- /dev/null +++ b/docs/stdlib/coding.rst @@ -0,0 +1,27 @@ +Code conversion +############### + +.. py:module:: nmigen.lib.coding + +The ``nmigen.lib.coding`` package provides modules for conversion between different encodings of binary numbers. + + +One-hot coding +============== + +.. autoclass:: Encoder() +.. autoclass:: Decoder() + + +Priority coding +=============== + +.. autoclass:: PriorityEncoder() +.. autoclass:: PriorityDecoder() + + +Gray coding +=========== + +.. autoclass:: GrayEncoder() +.. autoclass:: GrayDecoder() diff --git a/nmigen/lib/coding.py b/nmigen/lib/coding.py index 5abfbd7..aedff65 100644 --- a/nmigen/lib/coding.py +++ b/nmigen/lib/coding.py @@ -1,5 +1,3 @@ -"""Encoders and decoders between binary and one-hot representation.""" - from .. import * @@ -26,7 +24,7 @@ class Encoder(Elaboratable): i : Signal(width), in One-hot input. o : Signal(range(width)), out - Encoded binary. + Encoded natural binary. n : Signal, out Invalid: either none or multiple input bits are asserted. """ @@ -65,7 +63,7 @@ class PriorityEncoder(Elaboratable): i : Signal(width), in Input requests. o : Signal(range(width)), out - Encoded binary. + Encoded natural binary. n : Signal, out Invalid: no input bits are asserted. """ @@ -88,7 +86,7 @@ class PriorityEncoder(Elaboratable): class Decoder(Elaboratable): """Decode binary to one-hot. - If ``n`` is low, only the ``i``th bit in ``o`` is asserted. + If ``n`` is low, only the ``i``-th bit in ``o`` is asserted. If ``n`` is high, ``o`` is ``0``. Parameters @@ -141,7 +139,7 @@ class GrayEncoder(Elaboratable): Attributes ---------- i : Signal(width), in - Input natural binary. + Natural binary input. o : Signal(width), out Encoded Gray code. """ @@ -168,7 +166,7 @@ class GrayDecoder(Elaboratable): Attributes ---------- i : Signal(width), in - Input Gray code. + Gray code input. o : Signal(width), out Decoded natural binary. """ -- 2.30.2