Reorganized conf.py in a logical flow and sections for each plugin.

1 files changed, 168 insertions, 86 deletions

diff --git a/doc/conf.py b/doc/conf.py
index cf5be89e3..fe376e366 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -1,64 +1,31 @@
 # -*- coding: utf-8 -*-
-
 import sys, re
 from os.path import abspath
 from pathlib import Path
-from json import dump, loads
+from json import loads
 
 
 # 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, abspath('.'))
+sys.path.insert(0, abspath('..'))
+sys.path.insert(0, abspath('../pyGHDL'))
 
-# -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.5'
-
-extensions = [
-    # Standard Sphinx extensions
-    'recommonmark',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.extlinks',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx.ext.graphviz',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
-    # Other
-    'exec',
-]
-
-autodoc_default_options = {
-    "members": True,
-    'undoc-members': True,
-    #'private-members': True,
-    'inherited-members': True,
-}
-
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-source_suffix = {
-    '.rst': 'restructuredtext',
-    # '.txt': 'markdown',
-    '.md': 'markdown',
-}
-
-# The master toctree document.
-master_doc = 'index'
 
-# General information about the project.
+# ==============================================================================
+# Project information
+# ==============================================================================
 project = u'GHDL'
 copyright = u'2002-2020, Tristan Gingold and contributors'
 author = u'Tristan Gingold and contributors'
 
+# ==============================================================================
+# Versioning
+# ==============================================================================
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-
 try:
     with open('../configure') as verin:
         for line in verin:
@@ -73,21 +40,39 @@ except Exception as e:
 
 release = version  # The full version, including alpha/beta/rc tags.
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
+# ==============================================================================
+# Miscellaneous settings
+# ==============================================================================
+# The master toctree document.
+master_doc = 'index'
+
+# The suffix(es) of source filenames.
+source_suffix = {
+    '.rst': 'restructuredtext',
+    # '.txt': 'markdown',
+    '.md': 'markdown',
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+	"_build",
+	"_themes",
+	"Thumbs.db",
+	".DS_Store"
+]
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
-todo_link_only = True
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'stata-dark'
 
-# reST settings
+
+# ==============================================================================
+# Restructured Text settings
+# ==============================================================================
 prologPath = "prolog.inc"
 try:
     with open(prologPath, "r") as prologFile:
@@ -99,68 +84,157 @@ except Exception as ex:
 
 # -- Options for HTML output ----------------------------------------------
 
-html_logo = '_static/img/logo.png'
 
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'GHDLdoc'
+
+
+# ==============================================================================
+# 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 = Path(__file__).resolve().parent / 'context.json'
-if ctx.is_file():
-    html_context.update(loads(ctx.open('r').read()))
-
-html_theme_path = ["."]
-html_theme = "_theme"
-
 html_static_path = ['_static']
 html_extra_path = [str(Path(__file__).resolve().parent.parent / 'public')]
 
 html_logo = str(Path(html_static_path[0]) / 'logo.png')
 html_favicon = str(Path(html_static_path[0]) / 'icon.png')
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'GHDLdoc'
+html_context = {}
+ctx = Path(__file__).resolve().parent / 'context.json'
+if ctx.is_file():
+    html_context.update(loads(ctx.open('r').read()))
 
-# -- Options for LaTeX output ---------------------------------------------
+# ==============================================================================
+# Options for manual page output
+# ==============================================================================
+# One entry per manual page. List of tuples:
+man_pages = [(
+    master_doc,             # source start file
+    'ghdl',                 # name
+    u'GHDL Documentation',  # description
+    [author],               # authors
+    1                       # manual section
+)]
+
+
+# ==============================================================================
+# Options for LaTeX / PDF output
+# ==============================================================================
+# Grouping the document tree into Texinfo files. List of tuples:
+texinfo_documents = [(
+    master_doc,             # source start file
+    'GHDL',                 # target name
+    u'GHDL Documentation',  # title
+    author,                 # author
+    'GHDL',                 # dir menu entry
+    'VHDL simulator.',      # description
+    'Miscellaneous'         # category
+)]
+
+from textwrap import dedent
 
 latex_elements = {
-    'papersize': 'a4paper',
+	# The paper size ('letterpaper' or 'a4paper').
+	'papersize': 'a4paper',
+
+	# The font size ('10pt', '11pt' or '12pt').
+	#'pointsize': '10pt',
+
+	# Additional stuff for the LaTeX preamble.
+	'preamble': dedent(r"""
+		% ================================================================================
+		% User defined additional preamble code
+		% ================================================================================
+		% Add more Unicode characters for pdfLaTeX.
+		% - Alternatively, compile with XeLaTeX or LuaLaTeX.
+		% - https://github.com/sphinx-doc/sphinx/issues/3511
+		%
+		\ifdefined\DeclareUnicodeCharacter
+			\DeclareUnicodeCharacter{2265}{$\geq$}
+			\DeclareUnicodeCharacter{21D2}{$\Rightarrow$}
+		\fi
+
+		% ================================================================================
+		"""),
+
+	# Latex figure (float) alignment
+	#'figure_align': 'htbp',
 }
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, 'GHDL.tex', u'GHDL Documentation', author, 'manual'),
-]
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'ghdl', u'GHDL Documentation', [author], 1)
-]
+# ==============================================================================
+# Extensions
+# ==============================================================================
+extensions = [
+    # Standard Sphinx extensions
+    'sphinx.ext.autodoc',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.graphviz',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
 
-# -- Options for Texinfo output -------------------------------------------
+    # Other extensions
+    'recommonmark',
+    'exec',
+#     'DocumentMember',
+    'sphinx_fontawesome',
+    'sphinx_autodoc_typehints',
 
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author, dir menu entry, description, category)
-texinfo_documents = [
-  (master_doc, 'GHDL', u'GHDL Documentation', author, 'GHDL', 'VHDL simulator.', 'Miscellaneous'),
+    # local extensions (patched)
+    'autoapi.sphinx',
 ]
 
-# -- Sphinx.Ext.InterSphinx -----------------------------------------------
 
+# ==============================================================================
+# 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)
+   'poc': ('https://poc-library.readthedocs.io/en/release', None),
+   'vhdlmodel': ('https://vhdl.github.io/pyVHDLModel', None),
+}
+
+
+# ==============================================================================
+# Sphinx.Ext.AutoDoc
+# ==============================================================================
+# see: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+autodoc_member_order = "bysource"       # alphabetical, groupwise, bysource
+autodoc_default_options = {
+    "members": True,
+    'undoc-members': True,
+    #'private-members': True,
+    'inherited-members': True,
 }
 
-# -- Sphinx.Ext.ExtLinks --------------------------------------------------
+
+# ==============================================================================
+# Sphinx.Ext.Graphviz
+# ==============================================================================
+graphviz_output_format = "svg"
+
+
+# ==============================================================================
+# Sphinx.Ext.ToDo
+# ==============================================================================
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+todo_link_only = True
+
+
+# ==============================================================================
+# Sphinx.Ext.ExtLinks
+# ==============================================================================
 extlinks = {
    'wikipedia': ('https://en.wikipedia.org/wiki/%s', None),
    'ghdlsharp': ('https://github.com/ghdl/ghdl/issues/%s', '#'),
@@ -168,3 +242,11 @@ extlinks = {
    'ghdlpull':  ('https://github.com/ghdl/ghdl/pull/%s', 'pull request #'),
    'ghdlsrc':   ('https://github.com/ghdl/ghdl/blob/master/src/%s', None)
 }
+
+
+# ==============================================================================
+# AutoAPI.Sphinx
+# ==============================================================================
+autoapi_modules = {
+  'pyGHDL':  {'output': "pyGHDL", "override": True}
+}