Deploying to main from @ amaranth-lang/amaranth@d851580 🚀

docs/amaranth/latest/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 872fd82181381ceff32b86c0a89b074c
+config: ada5a5168775d40bd41f713658382264
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/amaranth/latest/_sources/lang.rst.txt

@@ -1300,7 +1300,7 @@ If the name of the domain is not known upfront, another, less concise, syntax ca
 
     add_video_domain(2)
 
-.. tip::
+.. note::
 
     Whenever the created :class:`ClockDomain` object is immediately assigned using the :pc:`domain_name = ClockDomain(...)` or :pc:`m.domains.domain_name = ClockDomain(...)` syntax, the name of the domain may be omitted from the :pc:`ClockDomain()` invocation. In other cases, it must be provided as the first argument.
 
@@ -1375,15 +1375,65 @@ The :class:`ClockSignal` and :class:`ResetSignal` values may also be assigned to
 Elaboration
 ===========
 
-.. todo:: Write this section.
+Amaranth designs are built from a hierarchy of smaller subdivisions, which are called *elaboratables*. The process of creating a data structure representing the behavior of a complete design by composing such subdivisions together is called *elaboration*.
 
+An elaboratable is any Python object that inherits from the :class:`Elaboratable` base class and implements the ``elaborate``  method:
 
-.. _lang-domainrenamer:
+.. testcode::
 
-Renaming domains
-----------------
+    class Counter(Elaboratable):
+        def elaborate(self, platform):
+            m = Module()
 
-.. todo:: Write this section about :class:`DomainRenamer`
+            ...
+
+            return m
+
+The ``elaborate`` method must either return an instance of :class:`Module` to describe the behavior of the elaboratable, or delegate it by returning another elaboratable object.
+
+.. note::
+
+    Instances of :class:`Module` also implement the ``elaborate`` method, which returns a special object that represents a fragment of a netlist. Such an object cannot be constructed without using :class:`Module`.
+
+The :pc:`platform` argument received by the ``elaborate`` method can be :pc:`None`, an instance of :ref:`a built-in platform <platform>`, or a custom object. It is used for `dependency injection <https://en.wikipedia.org/wiki/Dependency_injection>`_ and to contain the state of a design while it is being elaborated.
+
+.. important::
+
+    The ``elaborate`` method should not modify the ``self`` object it receives other than for debugging and experimentation. Elaborating the same design twice with two identical platform objects should produce two identical netlists. If the design needs to be modified after construction, this should happen before elaboration.
+
+    It is not possible to ensure that a design which modifies itself during elaboration is correctly converted to a netlist because the relative order in which the ``elaborate`` methods are called within a single design is not guaranteed.
+
+The Amaranth standard library provides *components*: elaboratable objects that also include a description of their interface. Unless otherwise necessary, an elaboratable should inherit from :class:`amaranth.lib.wiring.Component` rather than plain :class:`Elaboratable`. See the :ref:`introduction to interfaces and components <wiring-introduction>` for details.
+
+
+.. _lang-submodules:
+
+Submodules
+----------
+
+An elaboratable can be included within another elaboratable by adding it as a submodule:
+
+.. testcode::
+
+    m.submodules.counter = counter = Counter()
+
+If the name of a submodule is not known upfront, a different syntax should be used:
+
+.. testcode::
+
+    for n in range(3):
+        m.submodules[f"counter_{n}"] = Counter()
+
+A submodule can also be added without specifying a name:
+
+.. testcode::
+
+    counter = Counter()
+    m.submodules += counter
+
+.. tip::
+
+    If a name is not explicitly specified for a submodule, one will be generated and assigned automatically. Designs with many autogenerated names can be difficult to debug, so a name should usually be supplied.
 
 
 .. _lang-controlinserter:
@@ -1394,10 +1444,18 @@ Modifying control flow
 .. todo:: Write this section about :class:`ResetInserter` and :class:`EnableInserter`
 
 
+.. _lang-domainrenamer:
+
+Renaming domains
+----------------
+
+.. todo:: Write this section about :class:`DomainRenamer`
+
+
 .. _lang-memory:
 
-Memory arrays
-=============
+Memories
+========
 
 .. todo:: Write this section.
 

docs/amaranth/latest/_sources/platform.rst.txt

@@ -1,3 +1,5 @@
+.. _platform:
+
 Platform integration
 ####################
 

docs/amaranth/latest/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.4.1.dev24',
+    VERSION: '0.4.1.dev25',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/amaranth/latest/changes.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Changelog &mdash; Amaranth HDL toolchain 0.4.1.dev24 documentation</title>
+  <title>Changelog &mdash; Amaranth HDL toolchain 0.4.1.dev25 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/platformpicker.css" type="text/css" />
@@ -15,7 +15,7 @@
 
         <script src="_static/jquery.js?v=5d32c60e"></script>
         <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=f1c86904"></script>
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=55b0ed1d"></script>
         <script src="_static/doctools.js?v=888ff710"></script>
         <script src="_static/sphinx_highlight.js?v=4825356b"></script>
         <script src="_static/platformpicker.js"></script>
@@ -39,7 +39,7 @@
               <img src="_static/logo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                0.4.1.dev24+g4e1b245
+                0.4.1.dev25+gd851580
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">

docs/amaranth/latest/contrib.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Contributing &mdash; Amaranth HDL toolchain 0.4.1.dev24 documentation</title>
+  <title>Contributing &mdash; Amaranth HDL toolchain 0.4.1.dev25 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/platformpicker.css" type="text/css" />
@@ -15,7 +15,7 @@
 
         <script src="_static/jquery.js?v=5d32c60e"></script>
         <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=f1c86904"></script>
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=55b0ed1d"></script>
         <script src="_static/doctools.js?v=888ff710"></script>
         <script src="_static/sphinx_highlight.js?v=4825356b"></script>
         <script src="_static/platformpicker.js"></script>
@@ -38,7 +38,7 @@
               <img src="_static/logo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                0.4.1.dev24+g4e1b245
+                0.4.1.dev25+gd851580
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">

docs/amaranth/latest/cover.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Amaranth HDL documentation &mdash; Amaranth HDL toolchain 0.4.1.dev24 documentation</title>
+  <title>Amaranth HDL documentation &mdash; Amaranth HDL toolchain 0.4.1.dev25 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/platformpicker.css" type="text/css" />
@@ -15,7 +15,7 @@
 
         <script src="_static/jquery.js?v=5d32c60e"></script>
         <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=f1c86904"></script>
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=55b0ed1d"></script>
         <script src="_static/doctools.js?v=888ff710"></script>
         <script src="_static/sphinx_highlight.js?v=4825356b"></script>
         <script src="_static/platformpicker.js"></script>
@@ -38,7 +38,7 @@
               <img src="_static/logo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                0.4.1.dev24+g4e1b245
+                0.4.1.dev25+gd851580
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">

docs/amaranth/latest/genindex.html

@@ -3,7 +3,7 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Index &mdash; Amaranth HDL toolchain 0.4.1.dev24 documentation</title>
+  <title>Index &mdash; Amaranth HDL toolchain 0.4.1.dev25 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/platformpicker.css" type="text/css" />
@@ -14,7 +14,7 @@
 
         <script src="_static/jquery.js?v=5d32c60e"></script>
         <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=f1c86904"></script>
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=55b0ed1d"></script>
         <script src="_static/doctools.js?v=888ff710"></script>
         <script src="_static/sphinx_highlight.js?v=4825356b"></script>
         <script src="_static/platformpicker.js"></script>
@@ -36,7 +36,7 @@
               <img src="_static/logo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                0.4.1.dev24+g4e1b245
+                0.4.1.dev25+gd851580
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">

docs/amaranth/latest/index.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Language &amp; toolchain &mdash; Amaranth HDL toolchain 0.4.1.dev24 documentation</title>
+  <title>Language &amp; toolchain &mdash; Amaranth HDL toolchain 0.4.1.dev25 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/platformpicker.css" type="text/css" />
@@ -15,7 +15,7 @@
 
         <script src="_static/jquery.js?v=5d32c60e"></script>
         <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=f1c86904"></script>
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=55b0ed1d"></script>
         <script src="_static/doctools.js?v=888ff710"></script>
         <script src="_static/sphinx_highlight.js?v=4825356b"></script>
         <script src="_static/platformpicker.js"></script>
@@ -39,7 +39,7 @@
               <img src="_static/logo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                0.4.1.dev24+g4e1b245
+                0.4.1.dev25+gd851580
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
@@ -135,7 +135,7 @@ <h1>Language &amp; toolchain<a class="headerlink" href="#language-toolchain" tit
 <li class="toctree-l2"><a class="reference internal" href="lang.html#synchronous-evaluation">Synchronous evaluation</a></li>
 <li class="toctree-l2"><a class="reference internal" href="lang.html#clock-domains">Clock domains</a></li>
 <li class="toctree-l2"><a class="reference internal" href="lang.html#elaboration">Elaboration</a></li>
-<li class="toctree-l2"><a class="reference internal" href="lang.html#memory-arrays">Memory arrays</a></li>
+<li class="toctree-l2"><a class="reference internal" href="lang.html#memories">Memories</a></li>
 <li class="toctree-l2"><a class="reference internal" href="lang.html#instances">Instances</a></li>
 </ul>
 </li>

docs/amaranth/latest/install.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Installation &mdash; Amaranth HDL toolchain 0.4.1.dev24 documentation</title>
+  <title>Installation &mdash; Amaranth HDL toolchain 0.4.1.dev25 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/platformpicker.css" type="text/css" />
@@ -15,7 +15,7 @@
 
         <script src="_static/jquery.js?v=5d32c60e"></script>
         <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=f1c86904"></script>
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=55b0ed1d"></script>
         <script src="_static/doctools.js?v=888ff710"></script>
         <script src="_static/sphinx_highlight.js?v=4825356b"></script>
         <script src="_static/platformpicker.js"></script>
@@ -39,7 +39,7 @@
               <img src="_static/logo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                0.4.1.dev24+g4e1b245
+                0.4.1.dev25+gd851580
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">

docs/amaranth/latest/intro.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Introduction &mdash; Amaranth HDL toolchain 0.4.1.dev24 documentation</title>
+  <title>Introduction &mdash; Amaranth HDL toolchain 0.4.1.dev25 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/platformpicker.css" type="text/css" />
@@ -15,7 +15,7 @@
 
         <script src="_static/jquery.js?v=5d32c60e"></script>
         <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=f1c86904"></script>
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=55b0ed1d"></script>
         <script src="_static/doctools.js?v=888ff710"></script>
         <script src="_static/sphinx_highlight.js?v=4825356b"></script>
         <script src="_static/platformpicker.js"></script>
@@ -39,7 +39,7 @@
               <img src="_static/logo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                0.4.1.dev24+g4e1b245
+                0.4.1.dev25+gd851580
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">