New documentation structure for GHDL.

39 files changed, 688 insertions, 25 deletions

diff --git a/doc/0_Intro/.gitempty b/doc/0_Intro/.gitempty
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/0_Intro/.gitempty
diff --git a/doc/0_Intro/Contributing.rst b/doc/0_Intro/Contributing.rst
new file mode 100644
index 000000000..7a9b4fe75
--- /dev/null
+++ b/doc/0_Intro/Contributing.rst
@@ -0,0 +1,6 @@
+.. _INTRO:Contributing:
+
+Contributing
+############
+
+
diff --git a/doc/0_Intro/WhatIsGHDL.rst b/doc/0_Intro/WhatIsGHDL.rst
new file mode 100644
index 000000000..449ef5d01
--- /dev/null
+++ b/doc/0_Intro/WhatIsGHDL.rst
@@ -0,0 +1,29 @@
+.. include:: <isonum.txt>
+
+.. _INTRO:GHDL:
+
+What is `GHDL`?
+###############
+
+`GHDL` is a shorthand for G Hardware Design Language. Currently, `G` has no
+meaning.
+
+`GHDL` is a `VHDL` compiler that can execute (nearly) any `VHDL` program. `GHDL`
+is *not* a synthesis tool: you cannot create a netlist with `GHDL`.
+
+Unlike some other simulators, `GHDL` is a compiler: it directly translates a
+`VHDL` file to machine code, using the `GCC` or `LLVM` back-end and without
+using an intermediary language such as `C` or `C++`. Therefore, the compiled
+code should be faster and the analysis time should be shorter than with a
+compiler using an intermediary language.
+
+The Windows\ |trade| version of `GHDL` is not based on `GCC` but on an internal
+code generator.
+
+The current version of `GHDL` does not contain any graphical viewer: you cannot
+see signal waves. You can still check with a test bench. The current version can
+produce a `VCD` file which can be viewed with a wave viewer, as well as `ghw`
+files to be viewed by `gtkwave`.
+
+`GHDL` aims at implementing `VHDL` as defined by IEEE 1076. It supports most of
+the 1987 standard and most features added by the 1993 standard.
diff --git a/doc/0_Intro/WhatIsVHDL.rst b/doc/0_Intro/WhatIsVHDL.rst
new file mode 100644
index 000000000..b78ddda9a
--- /dev/null
+++ b/doc/0_Intro/WhatIsVHDL.rst
@@ -0,0 +1,29 @@
+.. _INTRO:VHDL:
+
+What is `VHDL`?
+###############
+
+`VHDL` is an acronym for Very High Speed Integrated Circuit Hardware Description
+Language which is a programming language used to describe a logic circuit by
+function, data flow behavior, or structure.
+
+`VHDL` *is* a programming language: although `VHDL` was not designed for writing
+general purpose programs, you can write any algorithm with the `VHDL` language.
+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`. `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`
+(hardware description language). 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.
+
+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 meaning.
+
+Like a program written in another hardware description language, a `VHDL`
+program can be transformed with a :dfn:`synthesis tool` into a netlist, that is,
+a detailed gate-level implementation.
diff --git a/doc/1_Using/InvokingGHDL.rst b/doc/1_Using/InvokingGHDL.rst
new file mode 100644
index 000000000..559b9f84e
--- /dev/null
+++ b/doc/1_Using/InvokingGHDL.rst
@@ -0,0 +1,6 @@
+.. _USING:Invoking:
+
+Invoking GHDL
+#############
+
+
diff --git a/doc/1_Using/QuickStartGuide.rst b/doc/1_Using/QuickStartGuide.rst
new file mode 100644
index 000000000..098749ec4
--- /dev/null
+++ b/doc/1_Using/QuickStartGuide.rst
@@ -0,0 +1,6 @@
+.. _USING:QuickStart:
+
+Quick Start Guide
+#################
+
+
diff --git a/doc/1_Using/Simulation.rst b/doc/1_Using/Simulation.rst
new file mode 100644
index 000000000..0246c20f4
--- /dev/null
+++ b/doc/1_Using/Simulation.rst
@@ -0,0 +1,6 @@
+.. _USING:Simulation:
+
+Simulation
+##########
+
+
diff --git a/doc/2_Releases/index.rst b/doc/2_Releases/index.rst
new file mode 100644
index 000000000..9e06f65af
--- /dev/null
+++ b/doc/2_Releases/index.rst
@@ -0,0 +1,6 @@
+.. _RELEASE:
+
+Releases
+########
+
+
diff --git a/doc/3_Building/index.rst b/doc/3_Building/index.rst
new file mode 100644
index 000000000..98468fd7f
--- /dev/null
+++ b/doc/3_Building/index.rst
@@ -0,0 +1,6 @@
+.. _BUILD:
+
+Building GHDL
+#############
+
+
diff --git a/doc/4_References/CommandReference.rst b/doc/4_References/CommandReference.rst
new file mode 100644
index 000000000..ed7869dba
--- /dev/null
+++ b/doc/4_References/CommandReference.rst
@@ -0,0 +1,6 @@
+.. _REF:Command:
+
+Command Reference
+#################
+
+
diff --git a/doc/4_References/ImplementationOfVHDL.rst b/doc/4_References/ImplementationOfVHDL.rst
new file mode 100644
index 000000000..aa2940c30
--- /dev/null
+++ b/doc/4_References/ImplementationOfVHDL.rst
@@ -0,0 +1,6 @@
+.. _REF:ImplVHDL:
+
+Building GHDL
+#############
+
+
diff --git a/doc/4_References/ImplementationOfVITAL.rst b/doc/4_References/ImplementationOfVITAL.rst
new file mode 100644
index 000000000..959058a2d
--- /dev/null
+++ b/doc/4_References/ImplementationOfVITAL.rst
@@ -0,0 +1,6 @@
+.. _REF:ImplVITAL:
+
+Building GHDL
+#############
+
+
diff --git a/doc/X_ChangeLog/2014/index.rst b/doc/X_ChangeLog/2014/index.rst
new file mode 100644
index 000000000..5822e67e7
--- /dev/null
+++ b/doc/X_ChangeLog/2014/index.rst
@@ -0,0 +1,20 @@
+.. _CHANGE:2014:
+
+2014
+####
+
+.. contents:: Content of this page
+   :local:
+   
+.. only:: html
+
+   .. toctree::
+   
+      v0.30 <v0.30>
+      
+      
+.. only:: latex
+
+   .. toctree::
+   
+      v0.30 <v0.30>
diff --git a/doc/X_ChangeLog/2014/v0.30.rst b/doc/X_ChangeLog/2014/v0.30.rst
new file mode 100644
index 000000000..87ebef22f
--- /dev/null
+++ b/doc/X_ChangeLog/2014/v0.30.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.30:
+
+New in 0.30 (xx.yy.2014)
+================================================================================================================================================================
diff --git a/doc/X_ChangeLog/2015/index.rst b/doc/X_ChangeLog/2015/index.rst
new file mode 100644
index 000000000..3a3dc1ed5
--- /dev/null
+++ b/doc/X_ChangeLog/2015/index.rst
@@ -0,0 +1,20 @@
+.. _CHANGE:2015:
+
+2015
+####
+
+.. contents:: Content of this page
+   :local:
+   
+.. only:: html
+
+   .. toctree::
+   
+      v0.31 <v0.31>
+      
+      
+.. only:: latex
+
+   .. toctree::
+   
+      v0.31 <v0.31>
diff --git a/doc/X_ChangeLog/2015/v0.31.rst b/doc/X_ChangeLog/2015/v0.31.rst
new file mode 100644
index 000000000..71bab8013
--- /dev/null
+++ b/doc/X_ChangeLog/2015/v0.31.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.31:
+
+New in 0.31 (xx.yy.2015)
+================================================================================================================================================================
diff --git a/doc/X_ChangeLog/2016/index.rst b/doc/X_ChangeLog/2016/index.rst
new file mode 100644
index 000000000..340fb915d
--- /dev/null
+++ b/doc/X_ChangeLog/2016/index.rst
@@ -0,0 +1,22 @@
+.. _CHANGE:2016:
+
+2016
+####
+
+.. contents:: Content of this page
+   :local:
+   
+.. only:: html
+
+   .. toctree::
+   
+      v0.33 <v0.33>
+      v0.32 <v0.32>      
+      
+      
+.. only:: latex
+
+   .. toctree::
+   
+      v0.32 <v0.32>
+      v0.33 <v0.33>
diff --git a/doc/X_ChangeLog/2016/v0.32.rst b/doc/X_ChangeLog/2016/v0.32.rst
new file mode 100644
index 000000000..ae6ff7a12
--- /dev/null
+++ b/doc/X_ChangeLog/2016/v0.32.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.32:
+
+New in 0.32 (xx.yy.2016)
+================================================================================================================================================================
diff --git a/doc/X_ChangeLog/2016/v0.33.rst b/doc/X_ChangeLog/2016/v0.33.rst
new file mode 100644
index 000000000..676390771
--- /dev/null
+++ b/doc/X_ChangeLog/2016/v0.33.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.33:
+
+New in 0.33 (xx.yy.2016)
+================================================================================================================================================================
diff --git a/doc/X_ChangeLog/2017/index.rst b/doc/X_ChangeLog/2017/index.rst
new file mode 100644
index 000000000..fa4ed0f1c
--- /dev/null
+++ b/doc/X_ChangeLog/2017/index.rst
@@ -0,0 +1,20 @@
+.. _CHANGE:2017:
+
+2017
+####
+
+.. contents:: Content of this page
+   :local:
+   
+.. only:: html
+
+   .. toctree::
+   
+      v0.34 <v0.34>
+      
+      
+.. only:: latex
+
+   .. toctree::
+   
+      v0.34 <v0.34>
diff --git a/doc/X_ChangeLog/2017/v0.34.rst b/doc/X_ChangeLog/2017/v0.34.rst
new file mode 100644
index 000000000..874a36728
--- /dev/null
+++ b/doc/X_ChangeLog/2017/v0.34.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.34:
+
+New in 0.34 (xx.yy.2017)
+================================================================================================================================================================
diff --git a/doc/X_ChangeLog/index.rst b/doc/X_ChangeLog/index.rst
new file mode 100644
index 000000000..385f7711a
--- /dev/null
+++ b/doc/X_ChangeLog/index.rst
@@ -0,0 +1,24 @@
+.. _CHANGE:
+
+Change Log
+##########
+
+.. only:: html
+
+   .. toctree::
+   
+      2017/index
+      2016/index
+      2015/index
+      2014/index
+      
+      
+      
+.. only:: latex
+
+   .. toctree::
+   
+      2014/index
+      2015/index
+      2016/index
+      2017/index
diff --git a/doc/_extensions/.gitempty b/doc/_extensions/.gitempty
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/_extensions/.gitempty
diff --git a/doc/_static/icons/.gitempty b/doc/_static/icons/.gitempty
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/_static/icons/.gitempty
diff --git a/doc/_static/images/.gitempty b/doc/_static/images/.gitempty
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/_static/images/.gitempty
diff --git a/doc/_static/logos/GitHub-Mark-32px.png b/doc/_static/logos/GitHub-Mark-32px.png
new file mode 100644
index 000000000..8b25551a9
--- /dev/null
+++ b/doc/_static/logos/GitHub-Mark-32px.png
diff --git a/doc/conf.py b/doc/conf.py
index 312e8398e..6364489f5 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -21,7 +21,10 @@ import subprocess
 # 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.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
+# sys.path.insert(0, os.path.abspath('../py'))
+sys.path.insert(0, os.path.abspath('_extensions'))
+# sys.path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme'))
 
 # -- General configuration ------------------------------------------------
 
@@ -31,10 +34,23 @@ import subprocess
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+# Standard Sphinx extensions
+	'sphinx.ext.extlinks',
+	'sphinx.ext.intersphinx',
+	'sphinx.ext.todo',
+	'sphinx.ext.graphviz',
+	'sphinx.ext.mathjax',
+	'sphinx.ext.ifconfig',
+	'sphinx.ext.viewcode',
+	# 'sphinx.ext.githubpages',
+# SphinxContrib extensions
+	# 'sphinxcontrib.textstyle',
+	# 'sphinxcontrib.spelling',
+]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['_templates', '_themes']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -124,8 +140,17 @@ pygments_style = 'sphinx'
 #keep_warnings = False
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+todo_include_todos = True
+todo_link_only = True
+
+# reST settings
 
+rst_prolog = """\
+.. |br| raw:: html
+
+   <br />
+   
+"""
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -230,7 +255,7 @@ htmlhelp_basename = 'GHDLdoc'
 
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+'papersize': 'a4paper',
 
 # The font size ('10pt', '11pt' or '12pt').
 #'pointsize': '10pt',
@@ -306,3 +331,20 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# ==============================================================================
+# Sphinx.Ext.InterSphinx
+# ==============================================================================
+intersphinx_mapping = {
+	'python': ('https://docs.python.org/3.5/', None)
+#	'ghdl':   ('http://ghdl.readthedocs.io/en/latest', None)
+}
+
+# ==============================================================================
+# Sphinx.Ext.ExtLinks
+# ==============================================================================
+extlinks = {
+	'ghdlissue': ('https://github.com/tgingold/ghdl/issues/%s', 'issue #'),
+	'ghdlpull':  ('https://github.com/tgingold/ghdl/pull/%s', 'pull request #'),
+	'ghdlsrc':   ('https://github.com/tgingold/ghdl/blob/master/src/%s', None)
+}
diff --git a/doc/genindex.rst b/doc/genindex.rst
new file mode 100644
index 000000000..c07da40d1
--- /dev/null
+++ b/doc/genindex.rst
@@ -0,0 +1,4 @@
+.. This file is a placeholder and will be replaced
+
+Index
+#####
diff --git a/doc/index.rst b/doc/index.rst
index fef600002..02a0889b5 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,28 +1,137 @@
-.. GHDL documentation master file, created by
-   sphinx-quickstart on Fri Nov 20 20:33:03 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. raw:: latex
 
-Welcome to GHDL's documentation!
-================================
+   \part{Introduction}
 
-Contents:
+This manual 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.
 
+
+--------------------------------------------------------------------------------
+
+.. only:: html
+
+   .. image:: /_static/logos/GitHub-Mark-32px.png
+      :scale: 60
+      :target: https://www.github.com/tgingold/ghdl
+      :alt: Source Code on GitHub
+   .. image:: https://travis-ci.org/tgingold/ghdl.svg?branch=release
+      :target: https://travis-ci.org/tgingold/ghdl
+      :alt: Build status by Travis-CI
+   .. image:: https://ci.appveyor.com/api/projects/status/r5dtv6amsppigpsp/branch/release?svg=true
+      :target: https://ci.appveyor.com/project/Paebbels/poc/branch/release
+      :alt: Build status by AppVeyor
+   .. image:: https://badges.gitter.im/ghdl/ghdl1.svg
+      :target: https://gitter.im/ghdl/ghdl1
+      :alt: Join
+      
+   .. raw:: html
+   
+      <br />
+      
+   .. image:: https://img.shields.io/github/tag/tgingold/ghdl.svg?style=flat
+      :alt: Latest tag
+   .. image:: https://img.shields.io/github/release/tgingold/ghdl.svg?style=flat
+      :target: https://github.com/tgingold/ghdl/releases
+      :alt: Latest release
+   .. image:: https://img.shields.io/github/license/tgingold/ghdl.svg?style=flat
+      :target: License.html
+      :alt: GNU General Public License 2
+      
+   .. raw:: html
+   
+      <hr />
+      
+      
+GHDL Documentation
+##################
+
+Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
+At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor
+sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
+accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet
+
+
+.. only:: html
+
+   News
+   ****
+   
+   23.10.2015 - GHDL 0.33 was released.
+   ====================================
+   
+.. only:: latex
+
+   .. rubric:: 23.10.2015 - GHDL 0.33 was released.
+   
+Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
+At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor
+sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
+accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet
+
+ 
+------------------------------------
+
+.. |docdate| date:: %b %d, %Y - %H:%M
+
+.. only:: html
+
+   This document was generated on |docdate|.
+   
+   
 .. toctree::
-   :maxdepth: 2
+   :caption: Introduction
+   :hidden:
+   
+   0_Intro/WhatIsVHDL
+   0_Intro/WhatIsGHDL
+   0_Intro/Contributing
+   License/gpl-2.0
+   
+.. raw:: latex
 
-   Introduction
-   Starting_with_GHDL
-   Invoking_GHDL
-   Simulation_and_runtime
-   GHDL_implementation_of_VHDL
-   GHDL_implementation_of_VITAL
-   Flaws_and_bugs_report
-   Copyrights
+   \part{GHDL usage}
+   
+.. toctree::
+   :caption: GHDL usage
+   :hidden:
+   
+   1_Using/QuickStartGuide
+   1_Using/InvokingGHDL
+   1_Using/Simulation
+   
+.. raw:: latex
 
-Indices and tables
-==================
+   \part{Getting GHDL}
+   
+.. toctree::
+   :caption: Getting GHDL
+   :hidden:
+   
+   2_Releases/index
+   3_Building/index
+   
+.. raw:: latex
 
-* :ref:`genindex`
-* :ref:`search`
+   \part{References}
+   
+.. toctree::
+   :caption: References
+   :hidden:
+   
+   4_References/CommandReference
+   4_References/ImplementationOfVHDL
+   4_References/ImplementationOfVITAL
+   
+.. raw:: latex
 
+   \part{Appendix}
+   
+.. toctree::
+   :caption: Appendix
+   :hidden:
+   
+   X_ChangeLog/index
+   genindex
+   
\ No newline at end of file
diff --git a/doc/make.ps1 b/doc/make.ps1
new file mode 100644
index 000000000..ad4eb4830
--- /dev/null
+++ b/doc/make.ps1
@@ -0,0 +1,242 @@
+# .SYNOPSIS
+# Please use '.\make.ps1 -<target>' where <target> is one of:
+#   html, dirhtml, singlehtml, pickle, json, linkcheck
+#
+# .DESCRIPTION
+# This is a front-end script for Sphinx.
+#
+# .EXAMPLE
+#  .\make.ps1 -clean
+# Cleanup the build directory.
+# .EXAMPLE
+#  .\make.ps1 -html
+# Build documentation as HTML pages.
+# .EXAMPLE
+#  .\make.ps1 -clean -html -linkcheck
+# Combine multiple commands in a single call
+#
+#
+# ==========================================================================
+# Copyright © 2016-2017 Patrick Lehmann - Dresden, Germany
+# ==========================================================================
+[CmdletBinding()]
+param(
+  # Make all targets
+  [switch]$all =        $false,
+  # Extract VHDL documentation
+  [switch]$html =       $false,
+  # Make HTML files named index.html in directories
+  [switch]$dirhtml =    $false,
+  # Make a single large HTML file
+  [switch]$singlehtml = $false,
+  # Make a PDF file
+  [switch]$latex =			$false,
+  [switch]$pdf =				$false,
+  # Make pickle files
+  [switch]$pickle =     $false,
+  # Make json files
+  [switch]$json =       $false,
+  # Check all external links for integrity
+  [switch]$linkcheck =  $false,
+  # Clean up directory before running Sphinx.
+  [switch]$clean =      $false,
+  # Show the embedded help page(s).
+  [switch]$help =       $false
+)
+
+# resolve paths
+$WorkingDir =     Get-Location
+$SphinxRootDir =  Convert-Path (Resolve-Path ($PSScriptRoot))
+
+# set default values
+$EnableVerbose =  $PSCmdlet.MyInvocation.BoundParameters["Verbose"]
+$EnableDebug =    $PSCmdlet.MyInvocation.BoundParameters["Debug"]
+if ($EnableVerbose -eq $null)  { $EnableVerbose =  $false }
+if ($EnableDebug   -eq $null)  { $EnableDebug =    $false }
+if ($EnableDebug   -eq $true)  { $EnableVerbose =  $true  }
+
+# Display help if no command was selected
+$Help = $Help -or (-not ($all -or $html -or $dirhtml -or $singlehtml -or $latex -or $pdf -or $json -or $pickle -or $linkcheck -or $clean -or $help))
+
+function Exit-Script
+{ <#
+    .PARAMETER ExitCode
+    ExitCode of this script run
+  #>
+  [CmdletBinding()]
+  param([int]$ExitCode = 0)
+  
+  # restore environment
+  # rm env:GHDL -ErrorAction SilentlyContinue
+  
+  cd $WorkingDir
+  
+  # unload modules
+  # Remove-Module precompile -Verbose:$false
+  
+	Pop-EnvironmentBlock
+  # exit with exit code
+  exit $ExitCode
+}
+
+if ($Help)
+{ Get-Help $MYINVOCATION.InvocationName -Detailed
+  Exit-Script
+}
+
+Push-EnvironmentBlock
+#$env:Path += ";C:\Tools\Graphviz\2.38\bin"
+
+if ($All)
+{ $clean =      $true
+  $html =       $true
+  $dirhtml =    $true
+  $singlehtml = $true
+}
+
+$SphinxBuild =    if (-not $env:SPHINXBUILD) { "sphinx-build" } else { $env:SPHINXBUILD }
+# $BuildDir =       "$SphinxRootDir\{{ rbuilddir }}"
+# $SourceDir =      "$SphinxRootDir\{{ rsrcdir }}"
+$BuildDir =       "$SphinxRootDir\_build"   # for local testing, can be removed in the future
+$SourceDir =      "$SphinxRootDir\."        # for local testing, can be removed in the future
+$AllSphinxOpts =  "-d $BuildDir\doctrees ${env:SPHINXOPTS} $SourceDir"
+$I18NSphinxOpts = "${env:SPHINXOPTS} $SourceDir"
+# ------------------------------------------------------------------------------
+# TODO: add paper options
+# ------------------------------------------------------------------------------
+# if NOT "%PAPER%" == "" (
+#   set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+#   set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+# )
+
+# Check if sphinx-build is available and fallback to Python version if any
+# ------------------------------------------------------------------------------
+# TODO: add testings if sphinxbuild can be called and/or is installed
+# ------------------------------------------------------------------------------
+#  %SPHINXBUILD% 1>NUL 2>NUL
+#  if errorlevel 9009 goto sphinx_python
+#  goto sphinx_ok
+#
+#  :sphinx_python
+#
+#  set SPHINXBUILD=python -m sphinx.__init__
+#  %SPHINXBUILD% 2> nul
+#  if errorlevel 9009 (
+#    echo.
+#    echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+#    echo.installed, then set the SPHINXBUILD environment variable to point
+#    echo.to the full path of the 'sphinx-build' executable. Alternatively you
+#    echo.may add the Sphinx directory to PATH.
+#    echo.
+#    echo.If you don't have Sphinx installed, grab it from
+#    echo.http://sphinx-doc.org/
+#    exit /b 1
+#  )
+
+
+if ($clean)
+{ $EnableVerbose -and (Write-Host "Cleaning build directory '$BuildDir'..." -Foreground DarkCyan  ) | Out-Null
+	$EnableDebug   -and (Write-Host "  dir -Path $BuildDir * -Directory | rmdir -Recurse"           ) | Out-Null
+	dir -Path $BuildDir * -Directory | rmdir -Recurse
+	
+  Write-Host "Cleaning finished." -Foreground Green
+}
+
+if ($html)
+{ $expr = "$SphinxBuild -b html -t GHDLInternal $AllSphinxOpts $BuildDir\html"
+  $EnableVerbose -and (Write-Host "Building target 'html' into '$BuildDir\html'..." -Foreground DarkCyan  ) | Out-Null
+	$EnableDebug   -and (Write-Host "  $expr" -Foreground Cyan ) | Out-Null
+	Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  Write-Host "Build finished. The HTML pages are in $BuildDir\html." -Foreground Green
+}
+
+if ($dirhtml)
+{ $expr = "$SphinxBuild -b dirhtml $AllSphinxOpts $BuildDir\dirhtml"
+  $EnableVerbose -and (Write-Host "Building target 'dirhtml' into '$BuildDir\dirhtml'..." -Foreground DarkCyan  ) | Out-Null
+	$EnableDebug   -and (Write-Host "  $expr" -Foreground Cyan ) | Out-Null
+  Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  Write-Host "Build finished. The HTML pages are in $BuildDir\dirhtml." -Foreground Green
+}
+
+if ($singlehtml)
+{ $expr = "$SphinxBuild -b singlehtml $AllSphinxOpts $BuildDir\singlehtml"
+  $EnableVerbose -and (Write-Host "Building target 'singlehtml' into '$BuildDir\singlehtml'..." -Foreground DarkCyan  ) | Out-Null
+	$EnableDebug   -and (Write-Host "  $expr" -Foreground Cyan ) | Out-Null
+  Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  Write-Host "Build finished. The HTML file is in $BuildDir\singlehtml." -Foreground Green
+}
+
+if ($latex)
+{ $expr = "$SphinxBuild -b latex $AllSphinxOpts $BuildDir\pdf"
+  $EnableVerbose -and (Write-Host "Building target 'latex' into '$BuildDir\pdf'..." -Foreground DarkCyan  ) | Out-Null
+	$EnableDebug   -and (Write-Host "  $expr" -Foreground Cyan ) | Out-Null
+  Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  Write-Host "Build finished. The LaTeX sources are in $BuildDir\pdf." -Foreground Green
+}
+if ($pdf)
+{	cd "$BuildDir\pdf"
+
+	cp "$BuildDir\pdf\GHDL.tex" "$BuildDir\pdf\GHDL.tex"
+	
+	$expr = "pdflatex.exe $BuildDir\pdf\GHDL.tex"
+	$EnableVerbose -and (Write-Host "Building target 'pdf' into '$BuildDir\pdf'..." -Foreground DarkCyan  ) | Out-Null
+	Write-Host "Compiling with pdflatex.exe..." -Foreground Yellow
+	$EnableDebug   -and (Write-Host "  $expr" -Foreground Cyan ) | Out-Null
+  Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  
+	$expr = "makeindex.exe .\GHDL.idx"
+	Write-Host "Creating index with makeindex.exe..." -Foreground Yellow
+	$EnableDebug   -and (Write-Host "  $expr" -Foreground Cyan ) | Out-Null
+  Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  
+	$expr = "pdflatex.exe $BuildDir\pdf\GHDL.tex"
+	Write-Host "Compiling with pdflatex.exe..." -Foreground Yellow
+  Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  Write-Host "Build finished. The PDF file is in $BuildDir\pdf." -Foreground Green
+}
+
+if ($pickle)
+{ $expr = "$SphinxBuild -b pickle $AllSphinxOpts $BuildDir\pickle"
+  $EnableVerbose -and (Write-Host "Building target 'pickle' into '$BuildDir\pickle'..." -Foreground DarkCyan  ) | Out-Null
+	$EnableDebug   -and (Write-Host "  $expr" -Foreground Cyan ) | Out-Null
+  Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  Write-Host "Build finished. Now you can process the pickle files." -Foreground Green
+}
+
+if ($json)
+{ $expr = "$SphinxBuild -b json $AllSphinxOpts $BuildDir\json"
+  $EnableVerbose -and (Write-Host "Building target 'json' into '$BuildDir\json'..." -Foreground DarkCyan  ) | Out-Null
+	$EnableDebug   -and (Write-Host "  $expr" -Foreground Cyan ) | Out-Null
+  Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  Write-Host "Build finished. Now you can process the json files." -Foreground Green
+}
+
+if ($linkcheck)
+{ $expr = "$SphinxBuild -b linkcheck $AllSphinxOpts $BuildDir\linkcheck"
+  $EnableVerbose -and (Write-Host "Building target 'html' into '$BuildDir\html'..." -Foreground DarkCyan  ) | Out-Null
+	$EnableDebug   -and (Write-Host "  $expr" -Foreground Cyan ) | Out-Null
+  Invoke-Expression $expr
+  if ($LastExitCode -ne 0)
+  { Exit-Script 1 }
+  Write-Host "Link check complete. Look for any errors in the above output or in $BuildDir\linkcheck\output.txt." -Foreground Green
+}
+
+Exit-Script
diff --git a/doc/Copyrights.rst b/doc/old_Copyrights.rst.txt
index 038a9291b..038a9291b 100644
--- a/doc/Copyrights.rst
+++ b/doc/old_Copyrights.rst.txt
diff --git a/doc/Flaws_and_bugs_report.rst b/doc/old_Flaws_and_bugs_report.rst.txt
index d4b269dc2..d4b269dc2 100644
--- a/doc/Flaws_and_bugs_report.rst
+++ b/doc/old_Flaws_and_bugs_report.rst.txt
diff --git a/doc/GHDL_implementation_of_VHDL.rst b/doc/old_GHDL_implementation_of_VHDL.rst.txt
index 5df2ec5d1..5df2ec5d1 100644
--- a/doc/GHDL_implementation_of_VHDL.rst
+++ b/doc/old_GHDL_implementation_of_VHDL.rst.txt
diff --git a/doc/GHDL_implementation_of_VITAL.rst b/doc/old_GHDL_implementation_of_VITAL.rst.txt
index 675510048..675510048 100644
--- a/doc/GHDL_implementation_of_VITAL.rst
+++ b/doc/old_GHDL_implementation_of_VITAL.rst.txt
diff --git a/doc/Introduction.rst b/doc/old_Introduction.rst.txt
index 135c8cb28..135c8cb28 100644
--- a/doc/Introduction.rst
+++ b/doc/old_Introduction.rst.txt
diff --git a/doc/Invoking_GHDL.rst b/doc/old_Invoking_GHDL.rst.txt
index f1f1c2e59..f1f1c2e59 100644
--- a/doc/Invoking_GHDL.rst
+++ b/doc/old_Invoking_GHDL.rst.txt
diff --git a/doc/Simulation_and_runtime.rst b/doc/old_Simulation_and_runtime.rst.txt
index 3714acb5c..3714acb5c 100644
--- a/doc/Simulation_and_runtime.rst
+++ b/doc/old_Simulation_and_runtime.rst.txt
diff --git a/doc/Starting_with_GHDL.rst b/doc/old_Starting_with_GHDL.rst.txt
index c7cd00f96..c7cd00f96 100644
--- a/doc/Starting_with_GHDL.rst
+++ b/doc/old_Starting_with_GHDL.rst.txt
diff --git a/doc/old_index.rst.txt b/doc/old_index.rst.txt
new file mode 100644
index 000000000..fef600002
--- /dev/null
+++ b/doc/old_index.rst.txt
@@ -0,0 +1,28 @@
+.. GHDL documentation master file, created by
+   sphinx-quickstart on Fri Nov 20 20:33:03 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to GHDL's documentation!
+================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   Introduction
+   Starting_with_GHDL
+   Invoking_GHDL
+   Simulation_and_runtime
+   GHDL_implementation_of_VHDL
+   GHDL_implementation_of_VITAL
+   Flaws_and_bugs_report
+   Copyrights
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+