From: Catherine <whitequark@whitequark.org>
Date: Mon, 13 Dec 2021 06:23:12 +0000 (+0000)
Subject: docs: cover `nmigen.lib.cdc`.
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=794a227b01979fa620eae9533d22cb40738bd49e;p=nmigen.git

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

diff --git a/docs/conf.py b/docs/conf.py
index 234fcb8..6b555c6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -30,6 +30,7 @@ todo_include_todos = True
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 napoleon_use_ivar = True
+napoleon_custom_sections = ["Platform overrides"]
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
diff --git a/docs/stdlib.rst b/docs/stdlib.rst
index 333db16..5dafadd 100644
--- a/docs/stdlib.rst
+++ b/docs/stdlib.rst
@@ -9,3 +9,4 @@ Standard library
    :maxdepth: 2
 
    stdlib/coding
+   stdlib/cdc
diff --git a/docs/stdlib/cdc.rst b/docs/stdlib/cdc.rst
new file mode 100644
index 0000000..596e69d
--- /dev/null
+++ b/docs/stdlib/cdc.rst
@@ -0,0 +1,13 @@
+Clock domain crossing
+#####################
+
+.. py:module:: nmigen.lib.cdc
+
+The ``nmigen.lib.cdc`` package provides modules for transferring data between clock domains.
+
+
+.. autoclass:: FFSynchronizer()
+.. autoclass:: AsyncFFSynchronizer()
+.. autoclass:: ResetSynchronizer()
+.. autoclass:: PulseSynchronizer()
+
diff --git a/nmigen/lib/cdc.py b/nmigen/lib/cdc.py
index a3f35f3..4bc5252 100644
--- a/nmigen/lib/cdc.py
+++ b/nmigen/lib/cdc.py
@@ -195,8 +195,8 @@ class ResetSynchronizer(Elaboratable):
         Maximum delay from the input signal's clock to the first synchronization stage, in seconds.
         If specified and the platform does not support it, elaboration will fail.
 
-    Platform override
-    -----------------
+    Platform overrides
+    ------------------
     Define the ``get_reset_sync`` platform method to override the implementation of
     :class:`ResetSynchronizer`, e.g. to instantiate library cells directly.
     """
@@ -219,9 +219,9 @@ class PulseSynchronizer(Elaboratable):
     """A one-clock pulse on the input produces a one-clock pulse on the output.
 
     If the output clock is faster than the input clock, then the input may be safely asserted at
-    100% duty cycle. Otherwise, if the clock ratio is `n`:1, the input may be asserted at most once
-    in every `n` input clocks, else pulses may be dropped. Other than this there is no constraint
-    on the ratio of input and output clock frequency.
+    100% duty cycle. Otherwise, if the clock ratio is ``n``:1, the input may be asserted at most
+    once in every ``n`` input clocks, else pulses may be dropped. Other than this there is
+    no constraint on the ratio of input and output clock frequency.
 
     Parameters
     ----------