Update doc (#1003)

* doc: update makefile and build scripts

* actions: add workflow 'doc'

* doc: reorganize sections

* doc: fix 'unknown option' warnings, headings, spaces, etc.

* doc: add subdir 'examples', move 'quick_start' sources

* doc: add section 'Development/Debugging'

* doc: add section'Development/Synthesis'

* doc: update roadmap

* doc: add section examples

* doc: use standard domain

* doc: add comment about 'vhd' vs 'vhdl'

2 files changed, 61 insertions, 0 deletions

diff --git a/doc/examples/quick_start/heartbeat/README.rst b/doc/examples/quick_start/heartbeat/README.rst
new file mode 100644
index 000000000..55f1e20c7
--- /dev/null
+++ b/doc/examples/quick_start/heartbeat/README.rst
@@ -0,0 +1,41 @@
+.. _QuickStart:heartbeat:
+
+`Heartbeat` module
+==================
+
+Although :ref:`Hello world <QuickStart:hello>` illustrates that `VHDL` is supported as a general purpose language, the main use case
+of `GHDL` is to simulate hardware descriptions. The following block, which is saved in a file named
+:file:`heartbeat.vhdl`, is an example of how to generate a 100 MHz clock signal with non-synthesisable VHDL:
+
+.. literalinclude:: heartbeat.vhdl
+   :language: vhdl
+
+It can be :ref:`analysed <Analysis:command>`, :ref:`elaborated <Elaboration:command>` and :ref:`run <Run:command>`, as you already know:
+
+.. code-block:: shell
+
+   ghdl -a heartbeat.vhdl
+   ghdl -e heartbeat
+   ghdl -r heartbeat
+
+However, execution of the design does not terminate. At the same time, no output is shown on screen. This is because,
+traditionally, hardware designs are continuously running devices which do not have a screen where to print. In this
+context, inspection and verification of the behaviour is done through `waveforms <https://en.wikipedia.org/wiki/Waveform_viewer>`_,
+which is supported by `GHDL` (see :ref:`export_waves`). You can use either :option:`--wave`, :option:`--vcd`,
+:option:`--vcdgz` or :option:`--fst` to save the signals of the simulation to a file. Then, terminate the execution
+(:kbd:`C-c`) and you can inspect the wave with a viewer, such as `GtkWave <http://gtkwave.sourceforge.net/>`_. As
+explained in the `manual <http://gtkwave.sourceforge.net/gtkwave.pdf>`_, GtkWave *'relies on a post-mortem approach
+through the use of dumpfiles'*. Therefore, you should first simulate your design and dump a waveform file, say GHW:
+
+.. code-block:: shell
+
+   ghdl -r --wave=wave.ghw heartbeat
+
+Then, you can view the dump:
+
+.. code-block:: shell
+
+   gtkwave wave.ghw
+
+Of course, manually terminating the simulation is for illustration purposes only. In :ref:`Full adder <QuickStart:adder>` and
+:ref:`QuickStart:DLX`, you will see how to write a testbench to terminate the simulation programmatically.
diff --git a/doc/examples/quick_start/heartbeat/heartbeat.vhdl b/doc/examples/quick_start/heartbeat/heartbeat.vhdl
new file mode 100644
index 000000000..0a312641e
--- /dev/null
+++ b/doc/examples/quick_start/heartbeat/heartbeat.vhdl
@@ -0,0 +1,20 @@
+library ieee;
+use ieee.std_logic_1164.all;
+
+entity heartbeat is
+  port ( clk: out std_logic);
+end heartbeat;
+
+architecture behaviour of heartbeat
+is
+  constant clk_period : time := 10 ns;
+begin
+  -- Clock process definition
+  clk_process: process
+  begin
+    clk <= '0';
+    wait for clk_period/2;
+    clk <= '1';
+    wait for clk_period/2;
+  end process;
+end behaviour;