Reorganising documentation

Also changing to furo theme.

docs/source/getting_started/examples.rst

@@ -0,0 +1,50 @@
+Example(s)
+----------
+
+.. _sec:typusecase:
+
+Typical use case
+~~~~~~~~~~~~~~~~
+
+The following example script may be used in a synthesis flow to convert the
+behavioural Verilog code from the input file design.v to a gate-level netlist
+synth.v using the cell library described by the Liberty file :
+
+.. code:: yoscrypt
+   :number-lines:
+
+   # read input file to internal representation
+   read_verilog design.v
+
+   # convert high-level behavioral parts ("processes") to d-type flip-flops and muxes
+   proc
+
+   # perform some simple optimizations
+   opt
+
+   # convert high-level memory constructs to d-type flip-flops and multiplexers
+   memory
+
+   # perform some simple optimizations
+   opt
+
+   # convert design to (logical) gate-level netlists
+   techmap
+
+   # perform some simple optimizations
+   opt
+
+   # map internal register types to the ones from the cell library
+   dfflibmap -liberty cells.lib
+
+   # use ABC to map remaining logic to cells from the cell library
+   abc -liberty cells.lib
+
+   # cleanup
+   opt
+
+   # write results to output file
+   write_verilog synth.v
+
+A detailed description of the commands available in Yosys can be found in
+:ref:`cmd_ref`.

docs/source/getting_started/index.rst

@@ -0,0 +1,8 @@
+Getting started with Yosys
+==========================
+
+.. toctree::
+
+	installation
+	scripting_intro
+	examples

docs/source/getting_started/installation.rst

@@ -0,0 +1,63 @@
+Installation
+------------
+
+Supported platforms
+~~~~~~~~~~~~~~~~~~~
+
+Source tree and build system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Yosys source tree is organized into the following top-level
+directories:
+
+-  | backends/
+   | This directory contains a subdirectory for each of the backend modules.
+
+-  | frontends/
+   | This directory contains a subdirectory for each of the frontend modules.
+
+-  | kernel/
+   | This directory contains all the core functionality of Yosys. This includes
+     the functions and definitions for working with the RTLIL data structures
+     (rtlil.h and rtlil.cc), the main() function (driver.cc), the internal
+     framework for generating log messages (log.h and log.cc), the internal
+     framework for registering and calling passes (register.h and register.cc),
+     some core commands that are not really passes (select.cc, show.cc, …) and a
+     couple of other small utility libraries.
+
+-  | passes/
+   | This directory contains a subdirectory for each pass or group of passes.
+     For example as of this writing the directory passes/opt/ contains the code
+     for seven passes: opt, opt_expr, opt_muxtree, opt_reduce, opt_rmdff,
+     opt_rmunused and opt_merge.
+
+-  | techlibs/
+   | This directory contains simulation models and standard implementations for
+     the cells from the internal cell library.
+
+-  | tests/
+   | This directory contains a couple of test cases. Most of the smaller tests
+     are executed automatically when make test is called. The larger tests must
+     be executed manually. Most of the larger tests require downloading external
+     HDL source code and/or external tools. The tests range from comparing
+     simulation results of the synthesized design to the original sources to
+     logic equivalence checking of entire CPU cores.
+
+The top-level Makefile includes frontends/\*/Makefile.inc,
+passes/\*/Makefile.inc and backends/\*/Makefile.inc. So when extending Yosys it
+is enough to create a new directory in frontends/, passes/ or backends/ with
+your sources and a Makefile.inc. The Yosys kernel automatically detects all
+commands linked with Yosys. So it is not needed to add additional commands to a
+central list of commands.
+
+Good starting points for reading example source code to learn how to write
+passes are passes/opt/opt_rmdff.cc and passes/opt/opt_merge.cc.
+
+See the top-level README file for a quick Getting Started guide and build
+instructions. The Yosys build is based solely on Makefiles.
+
+Users of the Qt Creator IDE can generate a QT Creator project file using make
+qtcreator. Users of the Eclipse IDE can use the "Makefile Project with Existing
+Code" project type in the Eclipse "New Project" dialog (only available after the
+CDT plugin has been installed) to create an Eclipse project in order to
+programming extensions to Yosys or just browse the Yosys code base.

docs/source/getting_started/scripting_intro.rst

@@ -0,0 +1,28 @@
+Scripting in Yosys
+------------------
+
+.. TODO: copypaste
+
+Yosys reads and processes commands from synthesis scripts, command line
+arguments and an interactive command prompt. Yosys commands consist of a command
+name and an optional whitespace separated list of arguments. Commands are
+terminated using the newline character or a semicolon (;). Empty lines and lines
+starting with the hash sign (#) are ignored. See :ref:`sec:typusecase` for an
+example synthesis script.
+
+The command ``help`` can be used to access the command reference manual.
+
+Most commands can operate not only on the entire design but also specifically on
+selected parts of the design. For example the command dump will print all
+selected objects in the current design while dump foobar will only print the
+module foobar and dump \* will print the entire design regardless of the current
+selection.
+
+.. code:: yoscrypt
+
+	dump */t:$add %x:+[A] \*/w:\* %i
+
+The selection mechanism is very powerful. For example the command above will
+print all wires that are connected to the ``\A`` port of a ``$add`` cell.
+Detailed documentation of the select framework can be found in the command
+reference for the ``select`` command.