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'

1 files changed, 49 insertions, 0 deletions

diff --git a/doc/examples/quick_start/README.rst b/doc/examples/quick_start/README.rst
new file mode 100644
index 000000000..6399996f5
--- /dev/null
+++ b/doc/examples/quick_start/README.rst
@@ -0,0 +1,49 @@
+.. _USING:QuickStart:
+
+Quick Start Guide
+#################
+
+Since this is the user and reference manual for `GHDL`, it does not contain an
+introduction to `VHDL`. Thus, the reader should have at least a basic knowledge
+of `VHDL`. A good knowledge of `VHDL` language reference manual (usually called
+LRM) is a plus. Nevertheless, multiple examples are provided, in the hope that
+they are useful for users to learn about both `GHDL` and `VHDL`. For advanced
+examples using specific features see :ref:`USING:Examples`.
+
+As explained in :ref:`INTRO:GHDL`, `GHDL` is a compiler which translates `VHDL` files to
+machine code. Hence, the regular workflow is composed of three steps:
+
+* :ref:`Analysis:command`: convert design units (`VHDL` sources) to an internal representation.
+* :ref:`Elaboration:command`: generate executable machine code for a target module (top-level entity).
+* :ref:`Run:command`: execute the design to test the behaviour, generate output/waveforms, etc.
+
+The following tips might be useful:
+
+* Don't forget to select the version of the VHDL standard you want to use (see
+  :ref:`VHDL_standards`). The default is :option:`--std=93c <--std>`. Use :option:`--std=08 <--std>` for VHDL-2008
+  (albeit not fully implemented).
+
+  * Use :option:`--ieee=synopsys <--ieee>` if your design depends on a non-standard implementation of the IEEE library.
+
+  * Use :option:`-fexplicit` and :option:`-frelaxed-rules` if needed.
+
+* Use :option:`--work=LIB_NAME <--work>` to analyze files into the ``LIB_NAME`` library.
+  To use files analyzed to a different directory, give the path
+  to the ``LIB_NAME`` library using :option:`-P/path/to/name/directory/ <-P<DIRECTORY>>`.
+
+* Use the same options for analysis and elaboration. E.g., first analyse with ``ghdl -a --std=08 --work=mylib myfile.vhdl``;
+  and then elaborate and run with ``ghdl --elab-run --std=08 top``.
+
+Due to the fact that `VHDL` is processed as a general purpose language
+(instead of an `HDL`), all the language features are to be supported. I.e., `VHDL`
+sources do not need to be limited to the synthesisable subset. However, distinction
+between synthesisable and non-synthesisable (simulation-only) subsets is often misleading
+for users who are new to the language. Different examples are provided,
+in the hope of helping understand the different use cases:
+
+.. toctree::
+
+   hello/README
+   heartbeat/README
+   adder/README
+   DLXModelSuite