diff --git a/.gitmodules b/.gitmodules index 24cc9dd4e..e69de29bb 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +0,0 @@ -[submodule "doc/_themes/sphinx_rtd_theme"] - path = doc/_themes/sphinx_rtd_theme - url = https://github.com/Paebbels/sphinx_rtd_theme.git diff --git a/.idea/vcs.xml b/.idea/vcs.xml index 7636b5640..4cf761c29 100644 --- a/.idea/vcs.xml +++ b/.idea/vcs.xml @@ -3,7 +3,6 @@ - \ No newline at end of file diff --git a/doc/BlockStream/References/index.rst b/doc/BlockStream/References/index.rst index ef0316745..b975ebb98 100644 --- a/doc/BlockStream/References/index.rst +++ b/doc/BlockStream/References/index.rst @@ -3,6 +3,6 @@ References .. toctree:: - LibraryStatement + Library Use Context diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..d4bb2cbb9 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/_themes/.gitempty b/doc/_themes/.gitempty deleted file mode 100644 index e69de29bb..000000000 diff --git a/doc/_themes/sphinx_rtd_theme b/doc/_themes/sphinx_rtd_theme deleted file mode 160000 index 1c15a5af2..000000000 --- a/doc/_themes/sphinx_rtd_theme +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 1c15a5af2e3409bcc84dbf31451f41c57c9f0a63 diff --git a/doc/conf.py b/doc/conf.py index 356696b74..def3ca98d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -9,49 +9,36 @@ # 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. -import os -import sys -sys.path.insert(0, os.path.abspath('.')) -sys.path.insert(0, os.path.abspath('..')) -sys.path.insert(0, os.path.abspath('../pyVHDLParser')) -#sys.path.insert(0, os.path.abspath('_extensions')) -#sys.path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme')) +# +from json import loads +from os.path import abspath +from pathlib import Path +from sys import path as sys_path +from pyTooling.Packaging import extractVersionInformation -# ============================================================================== -# Project information -# ============================================================================== -project = "pyVHDLParser" -copyright = "2016-2021 Patrick Lehmann - Boetzingen, Germany" -author = "Patrick Lehmann" +sys_path.insert(0, abspath('.')) +sys_path.insert(0, abspath('..')) +sys_path.insert(0, abspath('../pyVHDLParser')) +sys_path.insert(0, abspath('_extensions')) +#sys_path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme')) # ============================================================================== -# Versioning +# Project information and 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. -from subprocess import check_output +project = "pyVHDLParser" -def _IsUnderGitControl(): - return (check_output(["git", "rev-parse", "--is-inside-work-tree"], universal_newlines=True).strip() == "true") - -def _LatestTagName(): - return check_output(["git", "describe", "--abbrev=0", "--tags"], universal_newlines=True).strip() - -# The full version, including alpha/beta/rc tags -version = "0.6" # The short X.Y version. -release = "0.6.4" # The full version, including alpha/beta/rc tags. -try: - if _IsUnderGitControl: - latestTagName = _LatestTagName()[1:] # remove prefix "v" - versionParts = latestTagName.split("-")[0].split(".") +packageInformationFile = Path(f"../{project}/__init__.py") +versionInformation = extractVersionInformation(packageInformationFile) - version = ".".join(versionParts[:2]) - release = latestTagName # ".".join(versionParts[:3]) -except: - pass +author = versionInformation.Author +copyright = versionInformation.Copyright +version = ".".join(versionInformation.Version.split(".")[:2]) # e.g. 2.3 The short X.Y version. +release = versionInformation.Version # ============================================================================== @@ -85,7 +72,7 @@ def _LatestTagName(): with open(prologPath, "r") as prologFile: rst_prolog = prologFile.read() except Exception as ex: - print("[ERROR:] While reading '{0!s}'.".format(prologPath)) + print(f"[ERROR:] While reading '{prologPath}'.") print(ex) rst_prolog = "" @@ -93,14 +80,27 @@ def _LatestTagName(): # ============================================================================== # Options for HTML output # ============================================================================== -# html_theme = 'alabaster' -html_theme = 'sphinx_rtd_theme' +html_theme_options = { + 'home_breadcrumbs': True, + '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" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +# Output file base name for HTML help builder. +htmlhelp_basename = 'pyVHDLParserDoc' + # If not None, a 'Last updated on:' timestamp is inserted at every page # bottom, using the given strftime format. # The empty string is equivalent to '%b %d, %Y'. @@ -126,7 +126,7 @@ def _LatestTagName(): % ================================================================================ % Add more Unicode characters for pdfLaTeX. % - Alternatively, compile with XeLaTeX or LuaLaTeX. - % - https://github.com/sphinx-doc/sphinx/issues/3511 + % - https://GitHub.com/sphinx-doc/sphinx/issues/3511 % \ifdefined\DeclareUnicodeCharacter \DeclareUnicodeCharacter{2265}{$\geq$} @@ -146,8 +146,8 @@ def _LatestTagName(): # author, documentclass [howto, manual, or own class]). latex_documents = [ ( master_doc, - 'pyVHDLParser.tex', - 'The pyVHDLParser Documentation', + 'pyVHDLParser.tex', + 'The pyVHDLParser Documentation', 'Patrick Lehmann', 'manual' ), @@ -159,9 +159,6 @@ def _LatestTagName(): # Extensions # ============================================================================== extensions = [ -# Sphinx theme - "sphinx_rtd_theme", - # Standard Sphinx extensions "sphinx.ext.autodoc", 'sphinx.ext.extlinks', @@ -176,13 +173,14 @@ def _LatestTagName(): # SphinxContrib extensions # 'sphinxcontrib.actdiag', + 'sphinxcontrib.mermaid', # 'sphinxcontrib.seqdiag', # 'sphinxcontrib.textstyle', # 'sphinxcontrib.spelling', # 'changelog', # BuildTheDocs extensions - 'btd.sphinx.autoprogram', +# 'btd.sphinx.autoprogram', # 'btd.sphinx.graphviz', # 'btd.sphinx.inheritance_diagram', @@ -192,7 +190,7 @@ def _LatestTagName(): 'sphinx_autodoc_typehints', # local extensions (patched) - 'autoapi.sphinx', +# 'autoapi.sphinx', # local extensions # 'DocumentMember' @@ -202,8 +200,7 @@ def _LatestTagName(): # Sphinx.Ext.InterSphinx # ============================================================================== intersphinx_mapping = { - 'python': ('https://docs.python.org/3', None), - 'vhdlmodel': ('https://vhdl.github.io/pyVHDLModel', None), + 'python': ('https://docs.python.org/3', None), } @@ -218,10 +215,9 @@ def _LatestTagName(): # Sphinx.Ext.ExtLinks # ============================================================================== extlinks = { - 'issue': ('https://github.com/Paebbels/pyVHDLParser/issues/%s', 'issue #'), - 'pull': ('https://github.com/Paebbels/pyVHDLParser/pull/%s', 'pull request #'), - 'src': ('https://github.com/Paebbels/pyVHDLParser/blob/master/pyVHDLParser/%s?ts=2', None), -# 'test': ('https://github.com/Paebbels/pyVHDLParser/blob/master/test/%s?ts=2', None) + "ghissue": ('https://GitHub.com/Paebbels/pyVHDLParser/issues/%s', 'issue #'), + "ghpull": ('https://GitHub.com/Paebbels/pyVHDLParser/pull/%s', 'pull request #'), + "ghsrc": ('https://GitHub.com/Paebbels/pyVHDLParser/blob/main/%s?ts=2', None), } @@ -235,7 +231,7 @@ def _LatestTagName(): # ============================================================================== # Sphinx.Ext.ToDo # ============================================================================== -# If true, ``todo`` and ``todoList`` produce output, else they produce nothing. +# If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True todo_link_only = True @@ -245,5 +241,5 @@ def _LatestTagName(): # AutoAPI.Sphinx # ============================================================================== autoapi_modules = { - 'pyVHDLParser': {'output': "pyVHDLParser"} + 'pyVHDLParser': {'output': "pyVHDLParser", "override": True} } diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 000000000..922152e96 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 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 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/pyVHDLParser/__init__.py b/pyVHDLParser/__init__.py index c8af26510..7dcc9abf9 100644 --- a/pyVHDLParser/__init__.py +++ b/pyVHDLParser/__init__.py @@ -34,7 +34,7 @@ __email__ = "Paebbels@gmail.com" __copyright__ = "2016-2021, Patrick Lehmann" __license__ = "Apache License, Version 2.0" -__version__ = "0.1.0" +__version__ = "0.6.5" __keywords__ = ["parser", "vhdl", "code generator", "hdl"] from pyTooling.Decorators import export