docs: cover amaranth.lib.coding.

amaranth/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.
     """

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"]

docs/index.rst

@@ -13,3 +13,4 @@ Language & toolchain
    start
    tutorial
    lang
+   stdlib

docs/stdlib.rst

@@ -0,0 +1,11 @@
+Standard library
+################
+
+.. todo::
+
+   Write this section.
+
+.. toctree::
+   :maxdepth: 2
+
+   stdlib/coding

docs/stdlib/coding.rst

@@ -0,0 +1,27 @@
+Code conversion
+###############
+
+.. py:module:: amaranth.lib.coding
+
+The ``amaranth.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()