Doc: add Overview diagram, fix shields in tables, use extlinks more

18 files changed, 305 insertions, 254 deletions

diff --git a/doc/_static/internals.png b/doc/_static/internals.png
new file mode 100644
index 000000000..4baed711b
--- /dev/null
+++ b/doc/_static/internals.png
diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css
index 4a5cae28e..c87b7353d 100644
--- a/doc/_static/theme_overrides.css
+++ b/doc/_static/theme_overrides.css
@@ -1,58 +1,3 @@
-/* Change font sizes*/
-html,body{font-size:98%;}
-p{font-size:95%;margin-bottom:12px}
-.wy-breadcrumbs li.wy-breadcrumbs-aside{font-size:95%}
-.rst-versions{font-size:50%}
-.rst-versions .rst-current-version {font-size: 165%}
-.rst-versions dd{font-size:175%}
-footer {font-size: 75%;}
-.rst-footer-buttons {font-size: 140%;}
-
-/*Shrink left nav to 260px*/
-.wy-nav-side,.rst-versions,.wy-side-nav-search,.wy-menu-vertical{width: 260px}
-.wy-nav-content-wrap{margin-left:260px;background:#fcfcfc;min-height:100%}
-@media screen and (max-width: 768px){
-  .wy-nav-top i {padding-top:7px}
-  .wy-nav-content-wrap{margin-left:0px}
-  .wy-nav-content-wrap.shift{margin-left:260px;position: static;}
-  .wy-nav-side.shift{width:260px;padding-bottom: 40px;}
-  .rst-versions{width:260px}
-  .wy-side-scroll{width:280px;}
+.rst-content img.shield {
+  max-width: unset;
 }
-
-/*Fix shields in small screens*/
-@media screen and (max-width: 768px){img{width: auto}}
-/*Fix shield sizes in WhoUsesGHDL*/
-.whouses>.wy-table-responsive img {width:auto;height:20px !important;;display:inline}
-.whouses>.wy-table-responsive td {text-align:center}
-.whouses>.wy-table-responsive>table>thead th{min-width:130px !important}
-.whouses>.wy-table-responsive td:last-child{text-align: left}
-
-/*Remove 1 indentation space in the sidemenu items*/
-.wy-menu-vertical li.current a, .wy-menu-vertical li.toctree-l2.current > a{padding:0.4045em 1.618em}
-.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a{padding: 0.4045em 1.8em}
-.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a{padding: 0.4045em 2.618em}
-
-/*Remove empty add*/
-div.wy-menu.rst-pro{display: none !important;max-width: 260px}
-
-/*Simplify 'versions' tab*/
-.rst-versions dt{display:none}
-.rst-versions dd a[href$='.rst'] {display: none}
-.rst-versions dd a[href$='/downloads/'] {display: none}
-.rst-versions .wy-form{display:none !important;}
-.rst-versions .rst-other-versions dd a{padding: 3px}
-.rst-versions .rst-other-versions strong dd a{color: #27AE60}
-.rst-versions .rst-other-versions hr{margin: 5px 0; margin-top: -14px}
-
-.rst-versions {border-top: none}
-
-/*Last doc build date*/
-.lastdocbuilddate {position:fixed;padding-top:30px;font-size:70%;color:#999}
-
-/*Reduce space between footnotes*/
-.footnotes > .wy-table-responsive {margin-top:-12px;margin-bottom:12px}
-
-/*Reduce margin below lists*/
-.rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {margin-bottom: 12px}
-.rst-content blockquote {margin-bottom: 12px;}
diff --git a/doc/_static/theme_overrides.old.css b/doc/_static/theme_overrides.old.css
new file mode 100644
index 000000000..4a5cae28e
--- /dev/null
+++ b/doc/_static/theme_overrides.old.css
@@ -0,0 +1,58 @@
+/* Change font sizes*/
+html,body{font-size:98%;}
+p{font-size:95%;margin-bottom:12px}
+.wy-breadcrumbs li.wy-breadcrumbs-aside{font-size:95%}
+.rst-versions{font-size:50%}
+.rst-versions .rst-current-version {font-size: 165%}
+.rst-versions dd{font-size:175%}
+footer {font-size: 75%;}
+.rst-footer-buttons {font-size: 140%;}
+
+/*Shrink left nav to 260px*/
+.wy-nav-side,.rst-versions,.wy-side-nav-search,.wy-menu-vertical{width: 260px}
+.wy-nav-content-wrap{margin-left:260px;background:#fcfcfc;min-height:100%}
+@media screen and (max-width: 768px){
+  .wy-nav-top i {padding-top:7px}
+  .wy-nav-content-wrap{margin-left:0px}
+  .wy-nav-content-wrap.shift{margin-left:260px;position: static;}
+  .wy-nav-side.shift{width:260px;padding-bottom: 40px;}
+  .rst-versions{width:260px}
+  .wy-side-scroll{width:280px;}
+}
+
+/*Fix shields in small screens*/
+@media screen and (max-width: 768px){img{width: auto}}
+/*Fix shield sizes in WhoUsesGHDL*/
+.whouses>.wy-table-responsive img {width:auto;height:20px !important;;display:inline}
+.whouses>.wy-table-responsive td {text-align:center}
+.whouses>.wy-table-responsive>table>thead th{min-width:130px !important}
+.whouses>.wy-table-responsive td:last-child{text-align: left}
+
+/*Remove 1 indentation space in the sidemenu items*/
+.wy-menu-vertical li.current a, .wy-menu-vertical li.toctree-l2.current > a{padding:0.4045em 1.618em}
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a{padding: 0.4045em 1.8em}
+.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a{padding: 0.4045em 2.618em}
+
+/*Remove empty add*/
+div.wy-menu.rst-pro{display: none !important;max-width: 260px}
+
+/*Simplify 'versions' tab*/
+.rst-versions dt{display:none}
+.rst-versions dd a[href$='.rst'] {display: none}
+.rst-versions dd a[href$='/downloads/'] {display: none}
+.rst-versions .wy-form{display:none !important;}
+.rst-versions .rst-other-versions dd a{padding: 3px}
+.rst-versions .rst-other-versions strong dd a{color: #27AE60}
+.rst-versions .rst-other-versions hr{margin: 5px 0; margin-top: -14px}
+
+.rst-versions {border-top: none}
+
+/*Last doc build date*/
+.lastdocbuilddate {position:fixed;padding-top:30px;font-size:70%;color:#999}
+
+/*Reduce space between footnotes*/
+.footnotes > .wy-table-responsive {margin-top:-12px;margin-bottom:12px}
+
+/*Reduce margin below lists*/
+.rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {margin-bottom: 12px}
+.rst-content blockquote {margin-bottom: 12px;}
diff --git a/doc/about.rst b/doc/about.rst
index fea576f21..088f98b3a 100644
--- a/doc/about.rst
+++ b/doc/about.rst
@@ -12,21 +12,28 @@ About
 What is `VHDL`?
 ===============
 
-:wikipedia:`VHDL <VHDL>` is an acronym for Very High Speed Integrated Circuit (:wikipedia:`VHSIC <VHSIC>`) Hardware
-Description Language (:wikipedia:`HDL <HDL>`), which is a programming language used to describe a logic circuit by
-function, data flow behavior, or structure.
-
-Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language, and you can write
-any algorithm with it.
-If you are able to write programs, you will find in VHDL features similar to those found in procedural languages such as
-`C`, `Python`, or `Ada`.
+:wikipedia:`VHDL <VHDL>` is an acronym for *Verification and Hardware Description Language* (:wikipedia:`HDL <HDL>`),
+which is a computer language used to describe a logic circuit by function, data flow behavior, or structure.
+
+.. NOTE::
+  Historically the 'V' in the language's acronym came from the Very High Speed Integrated Circuit (:wikipedia:`VHSIC <VHSIC>`),
+  which was the U.S. government program that funded the early work on the standard.
+  Changing the 'V' to mean *verification* reflects the language's increasing usage for verification as well as design.
+  See `VHDL 202X PAR <http://www.eda-twiki.org/twiki/pub/P1076/PrivateDocuments/Par1076_202X.pdf>`__ via :ref:`vasg:VHDL202X`.
+
+Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language: any algorithm can
+be written with it, it can interact with files, the environment, stdin and stdout, etc.
+VHDL has features similar to those found in procedural languages such as
+:wikipedia:`C <C_(programming_language)>`,
+:wikipedia:`Python <Python_(programming_language)>`,
+or :wikipedia:`Ada <Ada_(programming_language)>`.
 Indeed, VHDL derives most of its syntax and semantics from Ada. Knowing `Ada` is an advantage for learning VHDL (it is
 an advantage in general as well).
 
 However, VHDL was not designed as a general purpose language but as an `HDL`.
 As the name implies, VHDL aims at modeling or documenting electronics systems.
-Due to the nature of hardware components which are always running, VHDL is a highly concurrent language, built upon an
-event-based timing model.
+Due to the nature of hardware components --which are always running--, VHDL is a highly concurrent language, built upon
+an event-driven execution model.
 
 Like a program written in any other language, a VHDL program can be executed.
 Since VHDL is used to model designs, the term :dfn:`simulation` is often used instead of `execution`, with the same
@@ -41,18 +48,26 @@ Five revisions exist:
 `2002 <http://ieeexplore.ieee.org/document/1003477/>`__,
 `2008 <http://ieeexplore.ieee.org/document/4772740/>`__ and
 `2019 <https://ieeexplore.ieee.org/document/8938196>`__.
-The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`__).
+The standardization is handled by the :doc:`vasg:index`.
+Find on-going work towards *VHDL 202X* in `gitlab.com/IEEE-P1076/VHDL-Issues <https://gitlab.com/IEEE-P1076/VHDL-Issues/-/issues>`__.
 
 .. _INTRO:GHDL:
 
 What is GHDL?
 =============
 
+.. figure:: _static/internals.png
+   :width: 100%
+   :align: center
+   :target: internals/index.html
+
+   Architecture overview of the GHDL toolkit (CLI, libghdl, pyGHDL and ghdl-yosys-plugin).
+
 `GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning).
 It is a VHDL analyzer, compiler, simulator and (experimental) synthesizer that can process (nearly) any VHDL design.
 
 .. NOTE::
-  For almost 20 years, GHDL was *not* a synthesis tool: you could not create a netlist.
+  For almost 20 years, GHDL was *not* a synthesis tool: a netlist could not be created.
   Hence, most of the content in this documentation corresponds to the usage of GHDL as a compiler/simulator.
   See :ref:`USING:Synthesis` for further details regarding synthesis.
 
@@ -66,11 +81,10 @@ GHDL can use multiple back-ends, i.e. code generators, (`GCC <http://gcc.gnu.org
 :wikipedia:`GNU/Linux <Linux_distribution>`, :wikipedia:`Windows <Microsoft_Windows>` |trade| and
 :wikipedia:`macOS <MacOS>` |trade|; on x86, x86_64, armv6/armv7/aarch32/aarch64, ppc64, etc.
 
-The current version of GHDL does not contain any built-in graphical viewer: you cannot see signal waves.
-You can still check the behavior of your design with a test bench.
-Moreover, :ref:`GHW`, :wikipedia:`VCD <Value_change_dump>` or `FST` files can be produced, which can be viewed with a
-:wikipedia:`waveform viewer <Waveform_viewer>`,
-such as `GtkWave <http://gtkwave.sourceforge.net/>`__.
+The current version of GHDL does not contain any built-in graphical viewer: signal waves cannot be seen through GHDL.
+However, the behavior of the designs can still be checked through test benches and verification frameworks.
+Moreover, :ref:`GHW`, :wikipedia:`VCD <Value_change_dump>` or `FST` files can be produced, which can be viewed with an
+external :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`__.
 
 GHDL aims at implementing VHDL as defined by `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`__.
 It supports the
@@ -83,9 +97,12 @@ It supports the
 Several third party projects are supported:
 `Yosys <https://github.com/YosysHQ/yosys>`__
 (through the `ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`__)
-`cocotb <https://github.com/potentialventures/cocotb>`__
-(through the `VPI interface <https://en.wikipedia.org/wiki/Verilog_Procedural_Interface>`__),
-`VUnit <https://vunit.github.io/>`__, `OSVVM <http://osvvm.org/>`__, ...
+`cocotb <https://github.com/potentialventures/cocotb>`__,
+(through the :wikipedia:`VPI interface <Verilog_Procedural_Interface>`),
+`VUnit <https://vunit.github.io/>`__,
+`OSVVM <http://osvvm.org/>`__,
+:doc:`vhdlmodel:index`,
+...
 
 .. _INTRO:WHO:
 
diff --git a/doc/conf.py b/doc/conf.py
index 4071310a5..bae26d1ec 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -2,10 +2,14 @@
 import sys
 from os.path import abspath
 from pathlib import Path
-from json import loads
+from json import loads as json_loads
 
 from pyTooling.Packaging import extractVersionInformation
 
+
+ROOT = Path(__file__).resolve().parent
+
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -79,13 +83,24 @@ except Exception as ex:
 # ==============================================================================
 # Options for HTML output
 # ==============================================================================
-html_theme = "_theme"
-html_theme_path = ["."]
-html_theme_options = {
-    'logo_only': True,
-    'home_breadcrumbs': False,
-    'vcs_pageview_mode': 'blob',
-}
+html_context = {}
+ctx = ROOT / "context.json"
+if ctx.is_file():
+    html_context.update(json_loads(ctx.open("r").read()))
+
+if (ROOT / "_theme").is_dir():
+    html_theme_path = ["."]
+    html_theme = "_theme"
+    html_theme_options = {
+        "logo_only": True,
+        "home_breadcrumbs": False,
+        "vcs_pageview_mode": "blob",
+    }
+    html_css_files = [
+        "theme_overrides.css",
+    ]
+else:
+    html_theme = "alabaster"
 
 html_static_path = ['_static']
 # '/public' will contain the output from gnatdoc
@@ -94,10 +109,6 @@ html_extra_path = [str(Path(__file__).resolve().parent.parent / 'public')]   # F
 html_logo = str(Path(html_static_path[0]) / 'logo.png')
 html_favicon = str(Path(html_static_path[0]) / 'icon.png')
 
-html_context = {}
-ctx = Path(__file__).resolve().parent / 'context.json'
-if ctx.is_file():
-    html_context.update(loads(ctx.open('r').read()))
 
 # ==============================================================================
 # Options for manual page output
@@ -191,10 +202,11 @@ extensions = [
 # Sphinx.Ext.InterSphinx
 # ==============================================================================
 intersphinx_mapping = {
-   'python': ('https://docs.python.org/3.6/', None),
-   'cosim': ('https://ghdl.github.io/ghdl-cosim', None),
-   'poc': ('https://poc-library.readthedocs.io/en/release', None),
+   'python':    ('https://docs.python.org/3.6/', None),
+   'cosim':     ('https://ghdl.github.io/ghdl-cosim', None),
+   'poc':       ('https://poc-library.readthedocs.io/en/release', None),
    'vhdlmodel': ('https://vhdl.github.io/pyVHDLModel', None),
+   'vasg':      ('https://ieee-p1076.gitlab.io', None)
 }
 
 
@@ -229,11 +241,11 @@ todo_link_only = True
 # Sphinx.Ext.ExtLinks
 # ==============================================================================
 extlinks = {
-   'wikipedia': ('https://en.wikipedia.org/wiki/%s', None),
+   'wikipedia': ('https://en.wikipedia.org/wiki/%s', ''),
    'ghdlsharp': ('https://github.com/ghdl/ghdl/issues/%s', '#'),
    'ghdlissue': ('https://github.com/ghdl/ghdl/issues/%s', 'issue #'),
    'ghdlpull':  ('https://github.com/ghdl/ghdl/pull/%s', 'pull request #'),
-   'ghdlsrc':   ('https://github.com/ghdl/ghdl/blob/master/src/%s', None)
+   'ghdlsrc':   ('https://github.com/ghdl/ghdl/blob/master/src/%s', '')
 }
 
 
diff --git a/doc/contribute.rst b/doc/contribute.rst
index 8c39b1d37..ec7391635 100644
--- a/doc/contribute.rst
+++ b/doc/contribute.rst
@@ -52,9 +52,9 @@ Please, report issues through |SHIELD:bug-report|, as this allows us to categori
 to them. You can track the state and see how it's getting solved.
 
 .. IMPORTANT::
-   As suggested in the bug report template, please elaborate a `Minimal (non) Working Example` (`MWE <https://en.wikipedia.org/wiki/Minimal_Working_Example>`_)
+   As suggested in the bug report template, please elaborate a `Minimal (non) Working Example` (:wikipedia:`MWE <Minimal_Working_Example>`)
    prior to sending the report, so that the possible bug source is isolated. Should it fulfill the format requirements of
-   `issue-runner <https://github.com/eine/issue-runner>`_, you would be able to test your bug with the latest GHDL version.
+   `issue-runner <https://github.com/umarcor/issue-runner>`_, you would be able to test your bug with the latest GHDL version.
    Please do so in order to ensure that the bug is not solved already.
 
    Also, please include enough information in the bug report, for the maintainers to reproduce the problem. The template
diff --git a/doc/helpers.py b/doc/helpers.py
index 9baddf700..5d099e729 100644
--- a/doc/helpers.py
+++ b/doc/helpers.py
@@ -26,13 +26,19 @@ def printShieldSrc(label, alt, img, target, latex=False):
    if latex:
       if label[-6:] == '/total':
          label = label[:-6]
-      print('.. |l' + re.compile('[\W_]+').sub('', label) + '| replace:: `' + label + '`_')
-      print('.. _' + label + ': ' + target + '\n')
+      idx = re.compile('[\W_]+').sub('', label)
+      print(f"""
+.. |l{idx}| replace:: `{label}`_
+.. _{label}: {target}
+""")
    else:
-      print('.. |' + label + '| image:: '+ img + '\n',
-            '   :target: ' + target + '\n',
-            '   :height: 22\n',
-            '   :alt: ' + alt + '\n')
+      print(f'''
+.. |{label}| image:: {img}
+   :target: {target}
+   :height: 22
+   :alt: {alt}
+   :class: shield
+''')
 
 #
 # Create shields/badges from JSON file
diff --git a/doc/index.rst b/doc/index.rst
index e114f3965..58c5fcb16 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -129,68 +129,4 @@ GHDL
 
    .. rubric:: 23.10.2015 - GHDL 0.33 was released.
 
-.. toctree::
-   :caption: Introduction
-   :hidden:
-
-   about
-   getting
-   contribute
-   licenses
-
-.. raw:: latex
-
-   \part{Usage}
-
-.. toctree::
-   :caption: GHDL usage
-   :hidden:
-
-   quick_start/index
-   using/InvokingGHDL
-   using/Simulation
-   using/Synthesis
-   using/CommandReference
-   using/ImplementationOfVHDL
-   using/ImplementationOfVITAL
-
-.. raw:: latex
-
-   \part{Development}
-
-.. toctree::
-   :caption: Development
-   :hidden:
-
-   development/Directories
-   Building GHDL <development/building/index>
-   Python Interfaces <pyGHDL/pyGHDL>
-   ghw/index
-   development/Debugging
-   development/CodingStyle
-   development/Scripts
-
-.. raw:: latex
-
-   \part{Internals}
-
-.. toctree::
-   :caption: Internals
-   :hidden:
-
-   internals/Overview
-   internals/Frontend
-   internals/AST
-   internals/RTI
-   gnatdoc/index
-
-.. raw:: latex
-
-   \part{Index}
-
-.. toctree::
-   :caption: Index
-   :hidden:
-
-   genindex
-   py-modindex
+.. include:: toc.rst
diff --git a/doc/internals/Overview.rst b/doc/internals/Overview.rst
deleted file mode 100644
index fd29f5832..000000000
--- a/doc/internals/Overview.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-.. _INT:Overview:
-
-Overview
-########
-
-.. image:: img/internals.png
-   :width: 350px
-   :align: center
-
-`GHDL` is architectured like a traditionnal compiler. It has:
-
-* a driver (sources in :ghdlsrc:`src/ghdldrv <ghdldrv>`) to call the programs (compiler, assembler, linker) if needed.
-
-* a runtime library named GRT (sources in :ghdlsrc:`src/grt <grt>`) to help execution at run-time. This ensures that execution is cycle-accurate.
-
-* a front-end (sources in :ghdlsrc:`src/vhdl <vhdl>`) to parse and analyse VHDL. See :ref:`INT:Frontend` and :ref:`INT:AST`.
-
-* multiple back-ends to generate either code or netlists.
-
-  * Three for :ref:`simulation <USING:Simulation>` (sources are in :ghdlsrc:`src/ortho <ortho>`): mcode, LLVM and GCC. See :ref:`BUILD`.
-  * Two for :ref:`synthesis <USING:Synthesis>` (sources in :ghdlsrc:`src/synth <synth>`): :ref:`--synth <Synth:command>` and :ref:`Synth:plugin`.
-
-The architecture is modular. For example, the front-end in the ``libghdl`` library is used for the language server.
-
-The main work is performed by the front-end, which is documented in the next chapter.
diff --git a/doc/internals/img/internals.png b/doc/internals/img/internals.png
deleted file mode 100644
index cc6714287..000000000
--- a/doc/internals/img/internals.png
+++ /dev/null
diff --git a/doc/internals/index.rst b/doc/internals/index.rst
new file mode 100644
index 000000000..4614d0edc
--- /dev/null
+++ b/doc/internals/index.rst
@@ -0,0 +1,34 @@
+.. _INT:Overview:
+
+Overview
+########
+
+.. figure:: ../_static/internals.png
+   :width: 100%
+   :align: center
+
+   Architecture overview of the GHDL toolkit (CLI, libghdl, pyGHDL and ghdl-yosys-plugin).
+
+`GHDL` is architectured like a traditionnal compiler. It has:
+
+* a driver (sources in :ghdlsrc:`src/ghdldrv <ghdldrv>`) to call the programs (compiler, assembler, linker) if needed.
+
+* a runtime library named GRT (sources in :ghdlsrc:`src/grt <grt>`) to help execution at run-time.
+  This ensures that execution is cycle-accurate.
+
+* a front-end (sources in :ghdlsrc:`src/vhdl <vhdl>`) to parse and analyse VHDL.
+  See :ref:`INT:Frontend` and :ref:`INT:AST`.
+
+* multiple back-ends to generate either code or netlists.
+
+  * Three for :ref:`simulation <USING:Simulation>` (sources are in :ghdlsrc:`src/ortho <ortho>`): mcode, LLVM and GCC.
+    See :ref:`BUILD`.
+  * Two for :ref:`synthesis <USING:Synthesis>` (sources in :ghdlsrc:`src/synth <synth>`):
+    :ref:`--synth <Synth:command>` and :ref:`Synth:plugin`.
+
+The architecture is modular and some of the components are available through the shared library ``libghdl``.
+``libghdl`` is used by the :ref:`Synth:plugin`, the Language Server Protocol (LSP) server, and to fill the data of
+pyVHDLModel (see :doc:`vhdlmodel:index`).
+
+The main work with regard to understanding the VHDL language is performed by the front-end, which is documented in the
+next section.
diff --git a/doc/quick_start/simulation/adder/index.rst b/doc/quick_start/simulation/adder/index.rst
index 5ff607801..693d42ef3 100644
--- a/doc/quick_start/simulation/adder/index.rst
+++ b/doc/quick_start/simulation/adder/index.rst
@@ -5,8 +5,8 @@
 =================================
 
 Unlike :ref:`Heartbeat <QuickStart:heartbeat>`, the target hardware design in this example is written using the
-synthesisable subset of `VHDL`. It is a `full adder <https://en.wikipedia.org/wiki/Adder_(electronics)#Full_adder>`_
-described in a file named :file:`adder.vhdl`:
+synthesisable subset of `VHDL`. It is a :wikipedia:`full adder <Adder_(electronics)#Full_adder>` described in a file
+named :file:`adder.vhdl`:
 
 .. literalinclude:: adder.vhdl
    :language: vhdl
diff --git a/doc/quick_start/simulation/heartbeat/index.rst b/doc/quick_start/simulation/heartbeat/index.rst
index e95145095..57e348e89 100644
--- a/doc/quick_start/simulation/heartbeat/index.rst
+++ b/doc/quick_start/simulation/heartbeat/index.rst
@@ -4,14 +4,16 @@
 `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:
+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:
+It can be :ref:`analysed <Analysis:command>`, :ref:`elaborated <Elaboration:command>` and :ref:`run <Run:command>`, as
+you already know:
 
 .. code-block:: shell
 
@@ -21,7 +23,7 @@ It can be :ref:`analysed <Analysis:command>`, :ref:`elaborated <Elaboration:comm
 
 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>`_,
+context, inspection and verification of the behaviour is done through :wikipedia:`waveforms <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
@@ -38,5 +40,6 @@ Then, you can view the dump:
 
    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.
+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/quick_start/simulation/hello/index.rst b/doc/quick_start/simulation/hello/index.rst
index 104a12efa..005706df8 100644
--- a/doc/quick_start/simulation/hello/index.rst
+++ b/doc/quick_start/simulation/hello/index.rst
@@ -14,23 +14,26 @@ a file named :file:`hello.vhdl`:
 
    * Both ``.vhdl`` and ``.vhd`` extensions are used for `VHDL` source files, while ``.v`` is used for Verilog.
 
-      * Since, extension ``.vhd`` is also interpreted as a `Virtual Hard Disk <https://en.wikipedia.org/wiki/VHD_(file_format)>`_
-        file format, some users prefer ``.vhdl``, to avoid ambiguity. This is the case with `GHDL`'s codebase. However, in order
-        to maintain `backward-compatibility <https://en.wikipedia.org/wiki/8.3_filename>`_ with legacy DOS systems,
-        other users prefer ``.vhd``.
-
-   * Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the
-     latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default.
+      * Since, extension ``.vhd`` is also interpreted as a :wikipedia:`Virtual Hard Disk <VHD_(file_format)>` file
+        format, some users prefer ``.vhdl``, to avoid ambiguity.
+        This is the case with `GHDL`'s codebase.
+        However, in order to maintain :wikipedia:`backward-compatibility <https://en.wikipedia.org/wiki/8.3_filename>`
+        with legacy DOS systems, other users prefer ``.vhd``.
+
+   * Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used.
+     However, if you do, the latter should be used.
+     The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default.
      However, GHDL has a relaxing option, :option:`--mb-comments` (multi byte), to allow UTF-8 or other encodings in
      comments.
 
-- First, you have to compile the file; this is called :ref:`analysis <Analysis:command>` of a design file in `VHDL`
-  terms. Run ``ghdl -a hello.vhdl`` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which
-  describes the library ``work``.
-- Then, run ``ghdl -e hello_world`` in the `shell`. Command :option:`-e` means :ref:`elaborate <Elaboration:command>`,
-  which is used to build a design, with the ``hello_world`` entity at the top of the hierarchy.
-- Last, you can directly launch the simulation :ref:`running <Run:command>` ``ghdl -r hello_world`` in the `shell`. The
-  result of the simulation will be shown on screen:
+* First, you have to compile the file; this is called :ref:`analysis <Analysis:command>` of a design file in `VHDL`
+  terms. Run ``ghdl -a hello.vhdl`` in the `shell`.
+  This command creates or updates a file :file:`work-obj93.cf`, which describes the library ``work``.
+* Then, run ``ghdl -e hello_world`` in the `shell`.
+  Command :option:`-e` means :ref:`elaborate <Elaboration:command>`, which is used to build a design, with the
+  ``hello_world`` entity at the top of the hierarchy.
+* Last, you can directly launch the simulation :ref:`running <Run:command>` ``ghdl -r hello_world`` in the `shell`.
+  The result of the simulation will be shown on screen:
 
 .. code-block:: shell
 
@@ -40,14 +43,15 @@ a file named :file:`hello.vhdl`:
    If a GCC/LLVM variant of `GHDL` is used:
 
    * :ref:`Analysis <Analysis:command>` generates a file, :file:`hello.o`, which is the object file corresponding to
-     your `VHDL` program. This is not created with :ref:`mcode <BUILD>`. These kind of object files can be
-     compiled into foreign programs (see :ref:`Linking_with_Ada`).
+     your `VHDL` program. This is not created with :ref:`mcode <BUILD>`.
+     These kind of object files can be compiled into foreign programs (see :ref:`Linking_with_Ada`).
    * The :ref:`elaboration <Elaboration:command>` step is mandatory after running the analysis and prior to launching the
-     simulation. This will generate an executable binary named :file:`hello_world`.
-   * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the
-     executable can be run directly: ``./hello_world``. See :option:`-r` for more informartion.
+     simulation.
+     This will generate an executable binary named :file:`hello_world`.
+   * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`.
+     Therefore, the executable can be run directly: ``./hello_world``. See :option:`-r` for more informartion.
 
 .. HINT::
-
-   :option:`-e` can be bypassed with :ref:`mcode <BUILD>`, since :option:`-r` actually elaborates the design and saves
-   it on memory before running the simulation. But you can still use it to check for some elaboration problems.
+  :option:`-e` can be bypassed with :ref:`mcode <BUILD>`, since :option:`-r` actually elaborates the design and saves
+  it on memory before running the simulation.
+  But you can still use it to check for some elaboration problems.
diff --git a/doc/quick_start/simulation/index.rst b/doc/quick_start/simulation/index.rst
index 8e41a453b..8feab2760 100644
--- a/doc/quick_start/simulation/index.rst
+++ b/doc/quick_start/simulation/index.rst
@@ -4,43 +4,39 @@
 Simulation
 ##########
 
-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).
+* 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:`--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>`.
+  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
+* 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:
+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::
 
diff --git a/doc/toc.rst b/doc/toc.rst
new file mode 100644
index 000000000..51c52fbf6
--- /dev/null
+++ b/doc/toc.rst
@@ -0,0 +1,65 @@
+.. toctree::
+   :caption: Introduction
+   :hidden:
+
+   about
+   getting
+   contribute
+   licenses
+
+.. raw:: latex
+
+   \part{Usage}
+
+.. toctree::
+   :caption: GHDL usage
+   :hidden:
+
+   quick_start/index
+   using/InvokingGHDL
+   using/Simulation
+   using/Synthesis
+   using/CommandReference
+   using/ImplementationOfVHDL
+   using/ImplementationOfVITAL
+
+.. raw:: latex
+
+   \part{Development}
+
+.. toctree::
+   :caption: Development
+   :hidden:
+
+   development/Directories
+   Building GHDL <development/building/index>
+   Python Interfaces <pyGHDL/pyGHDL>
+   ghw/index
+   development/Debugging
+   development/CodingStyle
+   development/Scripts
+
+.. raw:: latex
+
+   \part{Internals}
+
+.. toctree::
+   :caption: Internals
+   :hidden:
+
+   internals/index
+   internals/Frontend
+   internals/AST
+   internals/RTI
+   gnatdoc/index
+
+.. raw:: latex
+
+   \part{Index}
+
+.. toctree::
+   :caption: Index
+   :hidden:
+
+   genindex
+   py-modindex
diff --git a/doc/using/ImplementationOfVHDL.rst b/doc/using/ImplementationOfVHDL.rst
index a623801db..42681dcc9 100644
--- a/doc/using/ImplementationOfVHDL.rst
+++ b/doc/using/ImplementationOfVHDL.rst
@@ -142,7 +142,7 @@ or use a clocked expression (note the use of parentheses):
 
 Of course only the simple subset of PSL is allowed.
 
-Currently the built-in functions are not implemented, see `issue #662 <https://github.com/ghdl/ghdl/issues/662>`_.
+Currently the built-in functions are not implemented, see :ghdlsharp:`662`.
 PSL functions `prev()`, `stable()`, `rose()`, `fell()`, `onehot()` and `onehot0()` are supported with GHDL synthesis.
 
 PSL usage
diff --git a/pyGHDL/__init__.py b/pyGHDL/__init__.py
index bd5e1b8d7..8113f5254 100644
--- a/pyGHDL/__init__.py
+++ b/pyGHDL/__init__.py
@@ -39,12 +39,12 @@ GHDL offers two Python interfaces and a language server protocol service. All
 this is provided from a ``pyGHDL`` packages with four sub-packages:
 
 * ``pyGHDL.cli`` - Command line interface (CLI) applications.
-* ``pyGHDL.dom`` - A high-level API offering a document object model (DOM). The underlying abstract VHDL language model is
-  provided by `pyVHDLModel <https://github.com/VHDL/pyVHDLModel>`__. The DOM is using ``libghdl`` for file analysis and
-  parsing.
+* ``pyGHDL.dom`` - A high-level API offering a document object model (DOM).
+  The underlying abstract VHDL language model is provided by :doc:`pyVHDLModel <vhdlmodel:index>`.
+  The DOM is using ``libghdl`` for file analysis and parsing.
 * ``pyGHDL.libghdl`` - A low-level API directly interacting with the shared library ``libghdl....so``/``libghdl....dll``.
   This is a procedural and C-like interface. It comes with some Python generators for easier iterating linked lists.
-* ``pyGHDL.lsp`` - A `language server protocol <https://en.wikipedia.org/wiki/Language_Server_Protocol>`__ (LSP)
+* ``pyGHDL.lsp`` - A :wikipedia:`language server protocol <Language_Server_Protocol>` (LSP)
   written in Python. The implementation offers an HTTPS service that can be used e.g. by editors and IDEs supporting LSP.
 """
 __author__ = "Tristan Gingold and contributors"