doc: reorganise and update

11 files changed, 78 insertions, 26 deletions

diff --git a/doc/quick_start/index.rst b/doc/quick_start/index.rst
new file mode 100644
index 000000000..22c993855
--- /dev/null
+++ b/doc/quick_start/index.rst
@@ -0,0 +1,17 @@
+.. program:: ghdl
+.. _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 explained examples are provided, in the hope that they are useful for users to learn
+about both `GHDL` and `VHDL`.
+
+.. toctree::
+   :maxdepth: 2
+
+   simulation/index.rst
+   Co-Simulation <https://ghdl.github.io/ghdl-cosim>
+   python/index.rst
diff --git a/doc/quick_start/python/index.rst b/doc/quick_start/python/index.rst
new file mode 100644
index 000000000..83aea7db5
--- /dev/null
+++ b/doc/quick_start/python/index.rst
@@ -0,0 +1,33 @@
+.. program:: ghdl
+.. _USING:QuickStart:Python:
+
+Python Interfaces
+#################
+
+Currently, pyGHDL is not distributed through PyPI. Therefore, users need to install it from the git repository. However, the
+version of the sources must be compatible with the installed version of GHDL (and the shared library ``libghdl``).
+Installing from ``master`` is discouraged, because it might contain changes to the internal AST. Instead, ``ghdl version hash``
+allows getting the commit hash of the version the installed binary was built from. Since ``pip`` allows installing packages
+by providing the URL to the git repo, this is the recommended installation procedure:
+
+.. code-block::
+
+   pip install git+https://github.com/ghdl/ghdl.git@$(ghdl version hash)
+
+.. _CMDREF:
+
+Language Server
+***************
+
+When installed through ``pip``, pyGHDL provides executable entrypoints registered in the search PATH, such as ``ghdl-ls``.
+
+.. #
+   This files requires a Python module called 'AutoProgram' to be located in the
+   'doc' root folder. It expects a variable 'parser' of type ArgumentParser.
+
+.. _CMDREF-ghdlls:
+
+.. autoprogram:: AutoProgram:lsp_parser
+   :prog: ghdl-ls
+   :groups:
+   :label: CmdRef:ghdlls:
diff --git a/doc/quick_start/DLXModelSuite.rst b/doc/quick_start/simulation/DLXModelSuite.rst
index 0cdc8be86..0cdc8be86 100644
--- a/doc/quick_start/DLXModelSuite.rst
+++ b/doc/quick_start/simulation/DLXModelSuite.rst
diff --git a/doc/quick_start/adder/adder.vhdl b/doc/quick_start/simulation/adder/adder.vhdl
index cf60e8fbe..cf60e8fbe 100644
--- a/doc/quick_start/adder/adder.vhdl
+++ b/doc/quick_start/simulation/adder/adder.vhdl
diff --git a/doc/quick_start/adder/adder_tb.vhdl b/doc/quick_start/simulation/adder/adder_tb.vhdl
index 4a3fca5e4..4a3fca5e4 100644
--- a/doc/quick_start/adder/adder_tb.vhdl
+++ b/doc/quick_start/simulation/adder/adder_tb.vhdl
diff --git a/doc/quick_start/adder/README.rst b/doc/quick_start/simulation/adder/index.rst
index 5ff607801..5ff607801 100644
--- a/doc/quick_start/adder/README.rst
+++ b/doc/quick_start/simulation/adder/index.rst
diff --git a/doc/quick_start/heartbeat/heartbeat.vhdl b/doc/quick_start/simulation/heartbeat/heartbeat.vhdl
index 0a312641e..0a312641e 100644
--- a/doc/quick_start/heartbeat/heartbeat.vhdl
+++ b/doc/quick_start/simulation/heartbeat/heartbeat.vhdl
diff --git a/doc/quick_start/heartbeat/README.rst b/doc/quick_start/simulation/heartbeat/index.rst
index e95145095..e95145095 100644
--- a/doc/quick_start/heartbeat/README.rst
+++ b/doc/quick_start/simulation/heartbeat/index.rst
diff --git a/doc/quick_start/hello/hello.vhdl b/doc/quick_start/simulation/hello/hello.vhdl
index 4d969c6a8..4d969c6a8 100644
--- a/doc/quick_start/hello/hello.vhdl
+++ b/doc/quick_start/simulation/hello/hello.vhdl
diff --git a/doc/quick_start/hello/README.rst b/doc/quick_start/simulation/hello/index.rst
index 104a12efa..104a12efa 100644
--- a/doc/quick_start/hello/README.rst
+++ b/doc/quick_start/simulation/hello/index.rst
diff --git a/doc/quick_start/README.rst b/doc/quick_start/simulation/index.rst
index fc5f1a81a..8e41a453b 100644
--- a/doc/quick_start/README.rst
+++ b/doc/quick_start/simulation/index.rst
@@ -1,50 +1,52 @@
 .. program:: ghdl
-.. _USING:QuickStart:
+.. _USING:QuickStart:Simulation:
 
-Quick Start Guide
-#################
+Simulation
+##########
 
-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`.
+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:
 
-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.
+* :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).
+  :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:`--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. For instance, if you would like to use VHDL 2008
-    and also use shared variables with an ordinary type (deprecated in VHDL 2000), you can use ``--std=08 -frelaxed-rules``.
+  * Use :option:`-fexplicit` and :option:`-frelaxed-rules` if needed. For instance,
+    if you would like to use VHDL 2008 and also use shared variables with an
+    ordinary type (deprecated in VHDL 2000), you can use ``--std=08 -frelaxed-rules``.
 
 * 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>`.
 
-* 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``.
+* 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,
+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
+   hello/index
+   heartbeat/index
+   adder/index
    DLXModelSuite
+
+.. TIP:: See :ghdlissue:`Learning VHDL with GHDL <1291>`.