docs: lang.rst→guide.rst, add reference.rst.

whitequark · whitequark · commit c9b87a4fc547 · 2024-01-30T22:54:18.000Z
diff --git a/docs/guide.rst b/docs/guide.rst
@@ -10,7 +10,7 @@ Language guide
 
    This guide is a work in progress and is seriously incomplete!
 
-This guide introduces the Amaranth language in depth. It assumes familiarity with synchronous digital logic and the Python programming language, but does not require prior experience with any hardware description language. See the :doc:`tutorial <tutorial>` for a step-by-step introduction to the language.
+This guide introduces the Amaranth language in depth. It assumes familiarity with synchronous digital logic and the Python programming language, but does not require prior experience with any hardware description language. See the :doc:`tutorial <tutorial>` for a step-by-step introduction to the language, and the :doc:`reference <reference>` for a detailed description of the Python classes that underlie the language's syntax.
 
 .. TODO: link to a good synchronous logic tutorial and a Python tutorial?
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,7 +12,8 @@ Language & toolchain
    install
    start
    tutorial
-   lang
+   guide
+   reference
    stdlib
    platform
    changes
diff --git a/docs/intro.rst b/docs/intro.rst
@@ -16,7 +16,7 @@ The Amaranth toolchain consists of the :ref:`Amaranth language <intro-lang>`, th
 The Amaranth language
 =====================
 
-The :doc:`Amaranth hardware description language <lang>` is a Python library for register transfer level modeling of synchronous logic. Ordinary Python code is used to construct a netlist of a digital circuit, which can be simulated, directly synthesized via Yosys_, or converted to human-readable Verilog code for use with industry-standard toolchains.
+The :doc:`Amaranth hardware description language <guide>` is a Python library for register transfer level modeling of synchronous logic. Ordinary Python code is used to construct a netlist of a digital circuit, which can be simulated, directly synthesized via Yosys_, or converted to human-readable Verilog code for use with industry-standard toolchains.
 
 By relying on the flexibility, rich functionality and widespread adoption of the Python language, the Amaranth language is focused on a single task: modeling digital logic well. It has first-class support for building blocks like clock domains and finite state machines, and uses simple rules for arithmetic operations that closely match the Python semantics. Python classes, functions, loops and conditionals can be used to build organized and flexible designs; Python libraries can be seamlessly used with Amaranth during design or verification; and Python development tools can process Amaranth code.
 
diff --git a/docs/reference.rst b/docs/reference.rst
@@ -0,0 +1,8 @@
+Language reference
+##################
+
+.. warning::
+
+   This guide is a work in progress and is seriously incomplete!
+
+
diff --git a/docs/start.rst b/docs/start.rst
@@ -1,7 +1,7 @@
 Getting started
 ###############
 
-This section demonstrates the basic Amaranth workflow to provide a cursory overview of the language and the toolchain. See the :doc:`tutorial <tutorial>` for a step-by-step introduction to the language, and the :doc:`language guide <lang>` for a detailed explanation of every language construct.
+This section demonstrates the basic Amaranth workflow to provide a cursory overview of the language and the toolchain. See the :doc:`tutorial <tutorial>` for a step-by-step introduction to the language, and the :doc:`language guide <guide>` for a detailed explanation of every language construct.
 
 .. TODO: add link to build system doc
 .. TODO: add link to more complex examples?
