diff options
author | Patrick Lehmann <Patrick.Lehmann@tu-dresden.de> | 2017-02-19 04:57:17 +0100 |
---|---|---|
committer | tgingold <tgingold@users.noreply.github.com> | 2017-12-10 12:02:05 +0100 |
commit | e9f9a248facfcb9f249e7817bbc1264e2ea1ca32 (patch) | |
tree | 8accbb94a99dc60a0ac4fe8f54d19b285f22ad40 | |
parent | 7c1a8746d2b4fc076bcb287c8917af750a6b3d58 (diff) | |
download | ghdl-e9f9a248facfcb9f249e7817bbc1264e2ea1ca32.tar.gz ghdl-e9f9a248facfcb9f249e7817bbc1264e2ea1ca32.tar.bz2 ghdl-e9f9a248facfcb9f249e7817bbc1264e2ea1ca32.zip |
New documentation structure for GHDL.
40 files changed, 689 insertions, 25 deletions
diff --git a/.gitignore b/.gitignore index 0fd0bec87..59912be58 100644 --- a/.gitignore +++ b/.gitignore @@ -38,3 +38,4 @@ libgrt.a run-bind.adb run-bind.ads src/version.ads +doc/_build/ 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 Binary files differnew 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` + |