diff --git a/docs/lang.rst b/docs/guide.rst similarity index 99% rename from docs/lang.rst rename to docs/guide.rst index 81b9e57..c5d3228 100644 --- a/docs/lang.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 ` 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 ` for a step-by-step introduction to the language, and the :doc:`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 index 0e6e0df..0228708 100644 --- 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 index 2fed044..33ec2f2 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -16,7 +16,7 @@ The Amaranth toolchain consists of the :ref:`Amaranth language `, th The Amaranth language ===================== -The :doc:`Amaranth hardware description language ` 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 ` 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 new file mode 100644 index 0000000..e1f0205 --- /dev/null +++ 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 index 0be3a76..84a9aa1 100644 --- 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 ` for a step-by-step introduction to the language, and the :doc:`language guide ` 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 ` for a step-by-step introduction to the language, and the :doc:`language guide ` for a detailed explanation of every language construct. .. TODO: add link to build system doc .. TODO: add link to more complex examples?