From: Catherine <whitequark@whitequark.org>
Date: Mon, 13 Dec 2021 05:48:31 +0000 (+0000)
Subject: docs: cover `nmigen.lib.coding`.
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=728b60d2f565d13adb028603e2d3126eaa984ea8;p=nmigen.git

docs: cover `nmigen.lib.coding`.
---

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