diff --git a/.btd.yml b/.btd.yml new file mode 100644 index 0000000..0f45bcf --- /dev/null +++ b/.btd.yml @@ -0,0 +1,5 @@ +input: doc +output: _build +target: gh-pages +formats: [ html ] +theme: https://codeload.github.com/buildthedocs/sphinx.theme/tar.gz/v1 diff --git a/.github/workflows/Test.yml b/.github/workflows/Test.yml new file mode 100644 index 0000000..6243c01 --- /dev/null +++ b/.github/workflows/Test.yml @@ -0,0 +1,28 @@ +name: Doc + +on: + push: + schedule: + - cron: '0 0 * * 5' + workflow_dispatch: + +jobs: + + BTD: + name: '📓 Docs' + runs-on: ubuntu-latest + steps: + + - name: '🧰 Checkout' + uses: actions/checkout@v2 + + - name: '📓 BuildTheDocs (BTD)' + uses: buildthedocs/btd@v0 + with: + token: ${{ github.token }} + + - name: '📤 Upload artifact: HTML' + uses: actions/upload-artifact@master + with: + name: doc + path: doc/_build/html diff --git a/.gitignore b/.gitignore index 10e04b3..fe021b6 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,5 @@ build/ .idea/ +/doc/_build +/doc/_theme diff --git a/README.rst b/README.rst index 58dccfe..bc07969 100644 --- a/README.rst +++ b/README.rst @@ -1,34 +1,43 @@ - -======== Hdlparse -======== +######## -Hdlparse is a simple package implementing a rudimentary parser for VHDL and Verilog. It is not capable of fully parsing the entire language. Rather, it is meant to extract enough key information from a source file to create generated documentation. +Hdlparse is a simple package implementing a rudimentary parser for VHDL and Verilog. +It is not capable of fully parsing the entire language. +Rather, it is meant to extract enough key information from a source file to create generated documentation. -This library is forked from `kevinpt `_ via `zhelnio `_. The aim of this fork is to provide some bug fixes and additional features to zhelnio's version of Hdlparse. A list of changes is included at the bottom of this README. +This library is used by the `Symbolator `_ diagram generator. -For VHDL this library can extract component, subprogram, type, subtype, and constant declarations from a package. For Verilog it can extract module declarations (both 1995 and 2001 syntax). +For VHDL this library can extract component, subprogram, type, subtype, and constant declarations from a package. +For Verilog it can extract module declarations (both 1995 and 2001 syntax). Requirements ------------ -Hdlparse requires Python 3.x and no additional libraries. This version of Hdlparse is not compatible with Python2. +Hdlparse requires Python3 and no additional libraries. This version of Hdlparse is not compatible with Python2. Download -------- -You can access the Hdlparse Git repository from `Github -`_. You can install direct from PyPI with the "pip" -command if you have it available. +You can access the Hdlparse Git repository from `Github `_. +You can install direct from PyPI with the "pip" command if you have it available. + Installation ------------ -Hdlparse is a Python library. You must have Python installed first to use it. Most modern Linux distributions and OS/X have it available by default. There are a number of options available for Windows. If you don't already have a favorite, I recommend getting one of the `"full-stack" Python distros `_ that are geared toward scientific computing such as Anaconda or Python(x,y). +Hdlparse is a Python library. +You must have Python installed first to use it. +Most modern Linux distributions and OS/X have it available by default. +There are a number of options available for Windows. +If you don't already have a favorite, I recommend getting one of the +`"full-stack" Python distros `_ +that are geared toward scientific computing such as Anaconda or Python(x,y). -You need to have the Python setuptools installed first. If your OS has a package manager, it may be preferable to install setuptools through that tool. Otherwise you can use Pip: +You need to have the Python setuptools installed first. +If your OS has a package manager, it may be preferable to install setuptools through that tool. +Otherwise you can use Pip: .. code-block:: sh @@ -40,7 +49,9 @@ The easiest way to install Hdlparse is from `PyPI pip install --upgrade hdlparse -This will download and install the latest release, upgrading if you already have it installed. If you don't have ``pip`` you may have the ``easy_install`` command available which can be used to install ``pip`` on your system: +This will download and install the latest release, upgrading if you already have it installed. +If you don't have ``pip`` you may have the ``easy_install`` command available which can be used to install ``pip`` on +your system: .. code-block:: sh @@ -51,9 +62,10 @@ You can also use ``pip`` to get the latest development code from Github: .. code-block:: sh - > pip install --upgrade https://github.com/vvvverre/hdlparse/tarball/master + > pip install --upgrade https://github.com/hdl/pyHDLParser/tarball/main -If you manually downloaded a source package or created a clone with Git you can install with the following command run from the base Hdlparse directory: +If you manually downloaded a source package or created a clone with Git you can install with the following command run +from the base Hdlparse directory: .. code-block:: sh @@ -68,7 +80,7 @@ Documentation ------------- The full documentation is available online at the `main Hdlparse site -`_. +`_. Changes diff --git a/doc/.nojekyll b/doc/.nojekyll deleted file mode 100644 index e69de29..0000000 diff --git a/doc/Makefile b/doc/Makefile index e8dd567..9488e57 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,20 +1,37 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. +# Sphinx options. SPHINXOPTS = -SPHINXBUILD = python -msphinx -SPHINXPROJ = HdlParse -SOURCEDIR = . +SPHINXBUILD = sphinx-build +SPHINXPROJ = pyHDLParser +PAPER = BUILDDIR = _build -# Put it first so that "make" without argument is like "make help". +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees -T -D language=en $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +#--- + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + +#--- + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + +#--- + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + +#--- + .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) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/_static/Kreon-Bold.woff2 b/doc/_static/Kreon-Bold.woff2 deleted file mode 100644 index 40c6702..0000000 Binary files a/doc/_static/Kreon-Bold.woff2 and /dev/null differ diff --git a/doc/_static/Kreon-Light.woff2 b/doc/_static/Kreon-Light.woff2 deleted file mode 100644 index f2786a1..0000000 Binary files a/doc/_static/Kreon-Light.woff2 and /dev/null differ diff --git a/doc/_static/Kreon-Regular.woff2 b/doc/_static/Kreon-Regular.woff2 deleted file mode 100644 index ff2a7dd..0000000 Binary files a/doc/_static/Kreon-Regular.woff2 and /dev/null differ diff --git a/doc/_static/project.css b/doc/_static/project.css deleted file mode 100644 index 2d933f6..0000000 --- a/doc/_static/project.css +++ /dev/null @@ -1,143 +0,0 @@ - -@font-face { - font-family: 'Kreon'; - font-style: normal; - font-weight: 300; - src: local('Kreon Light'), local('Kreon-Light'), url('Kreon-Light.woff2') format('woff2'); -} -@font-face { - font-family: 'Kreon'; - font-style: normal; - font-weight: 400; - src: local('Kreon Regular'), local('Kreon-Regular'), url('Kreon-Regular.woff2') format('woff2'); -} -@font-face { - font-family: 'Kreon'; - font-style: normal; - font-weight: 700; - src: local('Kreon Bold'), local('Kreon-Bold'), url('Kreon-Bold.woff2') format('woff2'); -} - - -body { - font-size: medium; - background-color: white; - color: #000; - margin: 0; - padding: 0 1.1em 0 0; -} - -div.document { - width: 100%; - max-width: 1200px; - margin: 0 auto 0 auto; - padding: 0 0em 0 1em; -} - -pre, code { - font-size: small; -} - - -div.body h1, -div.body h2, -div.body h3, -div.body h4 { - font-family: "Kreon", "goudy old style", "minion pro", "bell mt", Georgia, "Hiragino Mincho Pro", serif; -} - -div.body h1, -div.body h2 { - font-weight: bold; -} - -div.sphinxsidebar p, -div.sphinxsidebar span, -div.sphinxsidebar h1, -div.sphinxsidebar h2, -div.sphinxsidebar h3, -div.sphinxsidebar h4 { - - font-family: "Kreon", "goudy old style", "minion pro", "bell mt", Georgia, "Hiragino Mincho Pro", serif; -} - -table.docutils { - border-left: 1px solid #aaa; - border-right: 1px solid #aaa; - border-top: 2px solid #92a6c4; - border-bottom: 4px solid #92a6c4; - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; - margin-bottom: 2em; -} - -table.docutils td, table.docutils th { - border-style: none; - padding: 0.25em 0.7em; -} - -table.docutils th { - border-bottom: 1px solid #92a6c4; -} - - -tt.descname { - font-size: 1.25em; -} - -pre { - background: #E9ECF5; - - -webkit-box-shadow: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24); - -moz-box-shadow: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24); - box-shadow: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24); -} - -dl.macro { - margin-top: 5em; -} - - -div.dl-button a, div.dl-button a:hover { - display: block; - height: 36px; - background: #008c00; - - color: white; - font: 16px/36px Helvetica, Verdana, sans-serif; - text-decoration: none; - text-align: center; - text-transform: uppercase; - - border: 4px solid white; - margin: 2px; - - -webkit-border-radius: 10px; - -moz-border-radius: 10px; - border-radius: 10px; - - -webkit-box-shadow: 0 2px 7px rgba(0,0,0,0.16), 0 3px 6px rgba(0,0,0,0.23); - -moz-box-shadow: 0 2px 7px rgba(0,0,0,0.16), 0 3px 6px rgba(0,0,0,0.23); - box-shadow: 0 2px 7px rgba(0,0,0,0.16), 0 3px 6px rgba(0,0,0,0.23); -} - -div.dl-button a:hover { - - /* Permalink - use to edit and share this gradient: http://colorzilla.com/gradient-editor/#008c00+0,007200+100 */ - background: #008c00; /* Old browsers */ - background: -moz-linear-gradient(top, #008c00 0%, #007200 100%); /* FF3.6+ */ - background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#008c00), color-stop(100%,#007200)); /* Chrome,Safari4+ */ - background: -webkit-linear-gradient(top, #008c00 0%,#007200 100%); /* Chrome10+,Safari5.1+ */ - background: -o-linear-gradient(top, #008c00 0%,#007200 100%); /* Opera 11.10+ */ - background: -ms-linear-gradient(top, #008c00 0%,#007200 100%); /* IE10+ */ - background: linear-gradient(to bottom, #008c00 0%,#007200 100%); /* W3C */ - filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#008c00', endColorstr='#007200',GradientType=0 ); /* IE6-9 */ - -} - -p.caption { - font-family: "Kreon", "goudy old style", "minion pro", "bell mt", Georgia, "Hiragino Mincho Pro", serif; - font-size: medium; - font-weight: bold; -} diff --git a/doc/_templates/download.html b/doc/_templates/download.html deleted file mode 100644 index a587e77..0000000 --- a/doc/_templates/download.html +++ /dev/null @@ -1,10 +0,0 @@ - diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html deleted file mode 100644 index 56d9ec7..0000000 --- a/doc/_templates/layout.html +++ /dev/null @@ -1,21 +0,0 @@ -{% extends "!layout.html" %} - -{% block extrahead %} -{{ super() }} - - - - - - -{% endblock %} - - diff --git a/doc/_templates/page.html b/doc/_templates/page.html deleted file mode 100644 index 1823180..0000000 --- a/doc/_templates/page.html +++ /dev/null @@ -1,5 +0,0 @@ -{% extends "!page.html" %} - -{% set css_files = css_files + ["_static/project.css", "_static/tty/tty-player.min.css"] %} - - diff --git a/doc/_templates/projects.html b/doc/_templates/projects.html deleted file mode 100644 index 5e35866..0000000 --- a/doc/_templates/projects.html +++ /dev/null @@ -1,77 +0,0 @@ -

Other projects

- -
-

-{% if project|lower != "opbasm" %}Opbasm
{% endif %} -{% if project|lower != "ripyl" %}Ripyl
{% endif %} -{% if project|lower != "vertcl" %}Vertcl
{% endif %} -{% if project|lower != "vhdl-extras" %}Vhdl-extras
{% endif %} -{% if project|lower != "lecroy colorizer" %}Lecroy-colorizer{% endif %} -

-
- - diff --git a/doc/about.rst b/doc/about.rst new file mode 100644 index 0000000..f175b42 --- /dev/null +++ b/doc/about.rst @@ -0,0 +1,20 @@ +About +##### + +Licensing +--------- + +pyHDLParser is distributed under the terms of the MIT license. + +Other projects +-------------- + +* `Evfs `__ +* `Guidoc `__ +* `LeCroy-colorizer `__ +* `Opbasm `__ +* `Ripyl `__ +* `Symbolator `__ +* `Syntrax `__ +* `VerTcl `__ +* `VHDL-extras `__ diff --git a/doc/apidoc/hdlparse.rst b/doc/apidoc/hdlparse.rst deleted file mode 100644 index 2b9e1d4..0000000 --- a/doc/apidoc/hdlparse.rst +++ /dev/null @@ -1,38 +0,0 @@ -hdlparse package -================ - -Submodules ----------- - -hdlparse\.minilexer module --------------------------- - -.. automodule:: hdlparse.minilexer - :members: - :undoc-members: - :show-inheritance: - -hdlparse\.verilog\_parser module --------------------------------- - -.. automodule:: hdlparse.verilog_parser - :members: - :undoc-members: - :show-inheritance: - -hdlparse\.vhdl\_parser module ------------------------------ - -.. automodule:: hdlparse.vhdl_parser - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: hdlparse - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/apidoc/modules.rst b/doc/apidoc/modules.rst deleted file mode 100644 index 47adae8..0000000 --- a/doc/apidoc/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -hdlparse -======== - -.. toctree:: - :maxdepth: 4 - - hdlparse diff --git a/doc/conf.py b/doc/conf.py index 10af14c..b85700b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,201 +1,111 @@ # -*- coding: utf-8 -*- -# -# HdlParse documentation build configuration file, created by -# sphinx-quickstart on Sun Oct 15 14:19:42 2017. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# 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. -# + +from json import loads +from pathlib import Path + import os import sys -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath("..")) -# -- General configuration ------------------------------------------------ -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' +# -- General configuration ------------------------------------------------ -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.githubpages', 'sphinx.ext.autodoc', 'sphinx.ext.napoleon'] +extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"] -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = [".rst"] -# The master toctree document. -master_doc = 'index' +master_doc = "index" -# General information about the project. -project = u'Hdlparse' -copyright = u'2017, Kevin Thibedeau' -author = u'Kevin Thibedeau' +project = u"pyHDLParser" +copyright = u"2017, Kevin Thibedeau and contributors" +author = u"Kevin Thibedeau" -# 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. -# def get_package_version(verfile): - '''Scan the script for the version string''' - version = None - with open(verfile) as fh: - try: - version = [line.split('=')[1].strip().strip("'") for line in fh if \ - line.startswith('__version__')][0] - except IndexError: - pass - return version - -# The short X.Y version. -version = get_package_version('../hdlparse/minilexer.py') -# The full version, including alpha/beta/rc tags. + """Scan the script for the version string""" + version = None + with open(verfile) as fh: + try: + version = [ + line.split("=")[1].strip().strip("'") + for line in fh + if line.startswith("__version__") + ][0] + except IndexError: + pass + return version + + +version = get_package_version("../hdlparse/minilexer.py") release = version -# 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 -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ["_build", "_theme", "Thumbs.db", ".DS_Store"] -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "stata-dark" -# If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False # -- Options for HTML output ---------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'alabaster' +html_theme_path = ["."] +html_theme = "_theme" -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} html_theme_options = { - 'description': 'HDL parsing library', - 'show_powered_by': False, - 'logo_text_align': 'center', - 'font_family': 'Verdana, Geneva, sans-serif', - 'github_user': 'kevinpt', - 'github_repo': 'hdlparse', - 'github_button': True -} - -# 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'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# This is required for the alabaster theme -# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars -html_sidebars = { - '**': [ - 'about.html', - 'relations.html', # needs 'show_related': True theme option to display - 'localtoc.html', - 'projects.html', - 'searchbox.html' - ], - - 'index': [ - 'about.html', - 'download.html', - 'relations.html', - 'localtoc.html', - 'projects.html', - 'searchbox.html' - ] + "logo_only": False, + "home_breadcrumbs": True, + "vcs_pageview_mode": "blob", } +html_context = {} -# -- Options for HTMLHelp output ------------------------------------------ +ctx = Path(__file__).resolve().parent / "context.json" +if ctx.is_file(): + html_context.update(loads(ctx.open("r").read())) -# Output file base name for HTML help builder. -htmlhelp_basename = 'HdlParsedoc' +#html_static_path = ["_static"] -# -- Options for LaTeX output --------------------------------------------- +# -- Options for HTMLHelp output ------------------------------------------ -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', +htmlhelp_basename = "pyHDLParserDoc" - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', +# -- Options for LaTeX output --------------------------------------------- - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} +latex_elements = {} -# 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, 'HdlParse.tex', u'HdlParse Documentation', - u'Kevin Thibedeau', 'manual'), + ( + master_doc, + "pyHDLParser.tex", + u"pyHDLParser Documentation", + u"Kevin Thibedeau", + "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, 'hdlparse', u'HdlParse Documentation', - [author], 1) -] +man_pages = [(master_doc, "hdlparse", u"pyHDLParser Documentation", [author], 1)] # -- Options for Texinfo output ------------------------------------------- -# 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, 'HdlParse', u'HdlParse Documentation', - author, 'HdlParse', 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + "pyHDLParser", + u"pyHDLParser Documentation", + author, + "pyHDLParser", + "One line description of project.", + "Miscellaneous", + ), ] - - - diff --git a/doc/genindex.rst b/doc/genindex.rst new file mode 100644 index 0000000..d4fc2f4 --- /dev/null +++ b/doc/genindex.rst @@ -0,0 +1,4 @@ +.. # This file is a placeholder and will be replaced + +Index +##### diff --git a/doc/getting.rst b/doc/getting.rst new file mode 100644 index 0000000..53149d5 --- /dev/null +++ b/doc/getting.rst @@ -0,0 +1,65 @@ +Getting +####### + +Requirements +------------ + +pyHDLParser requires either Python 2.7 or Python 3.x and no additional libraries. + +The installation script depends on setuptools. The source is written in +Python 2.7 syntax but will convert cleanly to Python 3 when the installer +passes it through ``2to3``. + +Download +-------- + +You can access the pyHDLParser Git repository from `Github `_. +You can install direct from PyPI with the ``pip`` command if you have it available. + +Installation +------------ + +pyHDLParser is a Python library. +You must have Python installed first to use it. +Most modern Linux distributions and OS/X have it available by default. +There are a number of options available for Windows. +If you don't already have a favorite, I recommend getting one of the `"full-stack" Python distros `_ that are geared toward scientific computing such as Anaconda or Python(x,y). + +You need to have the Python setuptools installed first. +If your OS has a package manager, it may be preferable to install setuptools through that tool. +Otherwise you can use Pip: + +.. code-block:: sh + + > pip install setuptools + +The easiest way to install pyHDLParser is from `PyPI `_. + +.. code-block:: sh + + > pip install --upgrade hdlparse + +This will download and install the latest release, upgrading if you already have it installed. +If you don't have ``pip`` you may have the ``easy_install`` command available which can be used to install ``pip`` on +your system: + +.. code-block:: sh + + > easy_install pip + +You can also use ``pip`` to get the latest development code from Github: + +.. code-block:: sh + + > pip install --upgrade https://github.com/hdl/pyHDLParser/tarball/master + +If you manually downloaded a source package or created a clone with Git you can install with the following command run +from the base pyHDLParser directory: + +.. code-block:: sh + + > python setup.py install + +On Linux systems you may need to install with root privileges using the *sudo* command. + +After a successful install the pyHDLParser library will be available. diff --git a/doc/index.rst b/doc/index.rst index ed57c68..8b9fc52 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,274 +1,18 @@ -.. HdlParse documentation master file, created by - sphinx-quickstart on Sun Oct 15 14:19:42 2017. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +pyHDLParser +########### -======== -Hdlparse -======== +pyHDLParser is a simple package implementing a rudimentary parser for VHDL and Verilog. +It is not capable of fully parsing the entire language. +Rather, it is meant to extract enough key information from a source file to create generated documentation. -Hdlparse is a simple package implementing a rudimentary parser for VHDL and Verilog. It is not capable of fully parsing the entire language. Rather, it is meant to extract enough key information from a source file to create generated documentation. - -This library is used by the `Symbolator `_ diagram generator. - -For VHDL this library can extract component, subprogram, type, subtype, and constant declarations from a package. For Verilog it can extract module declarations (both 1995 and 2001 syntax). - - -Requirements ------------- - -Hdlparse requires either Python 2.7 or Python 3.x and no additional libraries. - -The installation script depends on setuptools. The source is written in -Python 2.7 syntax but will convert cleanly to Python 3 when the installer -passes it through ``2to3``. - - -Licensing ---------- - -Opbasm and the included VHDL source is licensed for free commercial and non-commercial use under the terms of the MIT license. - - -Download --------- - -You can access the Hdlparse Git repository from `Github -`_. You can install direct from PyPI with the ``pip`` -command if you have it available. - -Installation ------------- - -Hdlparse is a Python library. You must have Python installed first to use it. Most modern Linux distributions and OS/X have it available by default. There are a number of options available for Windows. If you don't already have a favorite, I recommend getting one of the `"full-stack" Python distros `_ that are geared toward scientific computing such as Anaconda or Python(x,y). - -You need to have the Python setuptools installed first. If your OS has a package manager, it may be preferable to install setuptools through that tool. Otherwise you can use Pip: - -.. code-block:: sh - - > pip install setuptools - -The easiest way to install Hdlparse is from `PyPI `_. - -.. code-block:: sh - - > pip install --upgrade hdlparse - -This will download and install the latest release, upgrading if you already have it installed. If you don't have ``pip`` you may have the ``easy_install`` command available which can be used to install ``pip`` on your system: - -.. code-block:: sh - - > easy_install pip - - -You can also use ``pip`` to get the latest development code from Github: - -.. code-block:: sh - - > pip install --upgrade https://github.com/kevinpt/hdlparse/tarball/master - -If you manually downloaded a source package or created a clone with Git you can install with the following command run from the base Hdlparse directory: - -.. code-block:: sh - - > python setup.py install - -On Linux systems you may need to install with root privileges using the *sudo* command. - -After a successful install the Hdlparse library will be available. - - -Using Hdlparse --------------- - -The Hdlparse library has two main modules :py:mod:`~hdlparse.vhdl_parser` and :py:mod:`~hdlparse.verilog_parser`. You import one or both of them as needed. - -.. code-block:: python - - import hdlparse.vhdl_parser as vhdl - import hdlparse.verilog_parser as vlog - -Within each module are extractor classes :py:class:`~hdlparse.vhdl_parser.VhdlExtractor` and :py:class:`~hdlparse.verilog_parser.VerilogExtractor` that are the central mechanisms for using Hdlparse. - -.. code-block:: python - - vhdl_ex = vhdl.VhdlExtractor() - vlog_ex = vlog.VerilogExtractor() - - -VHDL -~~~~ - -The VHDL parser can extract a variety of different objects from sourec code. It can be used to access package definitions and component declarations,type and subtype definitions, functions, and procedures found within a package. It will not process entity declarations or nested subprograms and types. - -Extraction proceeds as follows: - -.. code-block:: python - - with io.open(fname, 'rt', encoding='latin-1') as fh: - code = fh.read() - vhdl_objs = vhdl_ex.extract_objects_from_source(code) - - vhdl_objs = vhdl_ex.extract_objects(fname) - -These will extract a list of all supported object types. The result is a list of objects subclassed from :py:class:`~hdlparse.vhdl_parser.VhdlObject`. You can pass an optional subclass of ``VhdlObject`` to filter the results for just that type. Repeated calls are more efficient when using :py:meth:`~hdlparse.vhdl_parser.VhdlExtractor.extract_objects` which maintains a cache of all previously parsed objects in the extractor. - -.. code-block:: vhdl - - package example is - component demo is - generic ( - GENERIC1: boolean := false; - GENERIC2: integer := 100 - ); - port ( - a, b : in std_ulogic := '1'; - c, d : out std_ulogic_vector(7 downto 0); - e, f : inout unsigned(7 downto 0) - ); - end component; - end package; - -Each port and generic is an instance of :py:class:`~hdlparse.vhdl_parser.VhdlParameter` containing the name, mode (input, output, inout), and type. - -.. code-block:: python - - import hdlparse.vhdl_parser as vhdl - from hdlparse.vhdl_parser import VhdlComponent - - vhdl_ex = vhdl.VhdlExtractor() - vhdl_comps = vhdl_ex.extract_objects('example.vhdl', VhdlComponent) - - for c in vhdl_comps: - print('Component "{}":'.format(c.name)) - - print(' Generics:') - for p in c.generics: - print('\t{:20}{:8} {}'.format(p.name, p.mode, p.data_type)) - - print(' Ports:') - for p in c.ports: - print('\t{:20}{:8} {}'.format(p.name, p.mode, p.data_type )) - -When run against the example code produces the following: - -.. code-block: console - - Component "demo": - Generics: - GENERIC1 in boolean - GENERIC2 in integer - Ports: - a in std_ulogic - b in std_ulogic - c out std_ulogic_vector(7 downto 0) - d out std_ulogic_vector(7 downto 0) - e inout unsigned(7 downto 0) - f inout unsigned(7 downto 0) - - -VHDL arrays -~~~~~~~~~~~ - -It can be useful to know which data types are an array. The :py:class:`~hdlparse.vhdl_parser.VhdlExtractor` class will keep track of all visited array type definitions it sees. The :py:meth:`~hdlparse.vhdl_parser.VhdlExtractor.is_array` method lets you query the internal list to check if a type is for an array. All IEEE standard array types are supported by default. Any subtypes derived from an array type will also be considered as arrays. - -.. code-block:: python - - import hdlparse.vhdl_parser as vhdl - - vhdl_ex = vhdl.VhdlExtractor() - - code = ''' - package foobar is - type custom_array is array(integer range <>) of boolean; - subtype custom_subtype is custom_array(1 to 10); - end package; - ''' - vhdl_comps = vhdl_ex.extract_objects(code) - - # These all return true: - print(vhdl_ex.is_array('unsigned')) - print(vhdl_ex.is_array('custom_array')) - print(vhdl_ex.is_array('custom_subtype')) - -Parsed array data can be saved to a file with :py:meth:`~hdlparse.vhdl_parser.VhdlExtractor.save_array_types` and restored with :py:meth:`~hdlparse.vhdl_parser.VhdlExtractor.load_array_types`. This lets you parse one set of files for type definitions and use the saved info for parsing other code at a different time. - - -Verilog -~~~~~~~ - -The Verilog parser is only able to extract module definitions with a port and optional parameter list. Verilog modules are extracted using the :py:meth:`~hdlparse.verilog_parser.VerilogExtractor.extract_objects` and :py:meth:`~hdlparse.verilog_parser.VerilogExtractor.extract_objects_from_source` methods. The latter is used when you have the code in a string. The former when you want to read the Veirlog source from a file. When parsing a file, a cache of objects is maintained so you can repeatedly call :py:meth:`~hdlparse.verilog_parser.VerilogExtractor.extract_objects` without reparsing the file. - -.. code-block:: python - - with open(fname, 'rt') as fh: - code = fh.read() - vlog_mods = vlog_ex.extract_objects_from_source(code) - - vlog_mods = vlog_ex.extract_objects(fname) - -The result is a list of extracted :py:class:`~hdlparse.verilog_parser.VerilogModule` objects. Each instance of this class has ``name``, ``generics``, and ``ports`` attributes. The ``name`` attribute is the name of the module. The ``generics`` attribute is a list of extracted parameters and ``ports`` is a list of the ports on the module. - -.. code-block:: verilog - - module newstyle // This is a new style module def - #(parameter real foo = 8, bar=1, baz=2, - parameter signed [7:0] zip = 100) - ( - input x, x2, inout y, y2_long_output, - output wire [4:1] z, z2 - ); - endmodule - -Each port and generic is an instance of :py:class:`~hdlparse.verilog_parser.VerilogParameter` containing the name, mode (input, output, inout), and type. - -.. code-block:: python - - import hdlparse.verilog_parser as vlog - - vlog_ex = vlog.VerilogExtractor() - vlog_mods = vlog_ex.extract_objects_from_source('example.v') - - for m in vlog_mods: - print('Module "{}":'.format(m.name)) - - print(' Parameters:') - for p in m.generics: - print('\t{:20}{:8}{}'.format(p.name, p.mode, p.data_type)) - - print(' Ports:') - for p in m.ports: - print('\t{:20}{:8}{}'.format(p.name, p.mode, p.data_type)) - - -When run against the example code produces the following: - -.. code-block:: console - - Module "newstyle": - Parameters: - foo in real - bar in real - baz in real - zip in signed [7:0] - Ports: - x input - x2 input - y inout - y2_long_output inout - z output wire [4:1] - z2 output wire [4:1] +This library is used by the `Symbolator `_ diagram generator. +For VHDL this library can extract component, subprogram, type, subtype, and constant declarations from a package. +For Verilog it can extract module declarations (both 1995 and 2001 syntax). .. toctree:: - :hidden: - :maxdepth: 2 - - apidoc/modules - - -Indices and tables ------------------- -* :ref:`genindex` -* :ref:`search` + about + getting + usage + genindex diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000..a051159 --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,241 @@ +Usage +##### + +The pyHDLParser library has two main modules :py:mod:`~hdlparse.vhdl_parser` and :py:mod:`~hdlparse.verilog_parser`. +You import one or both of them as needed. + +.. code-block:: python + + import hdlparse.vhdl_parser as vhdl + import hdlparse.verilog_parser as vlog + +Within each module are extractor classes :py:class:`~hdlparse.vhdl_parser.VhdlExtractor` and +:py:class:`~hdlparse.verilog_parser.VerilogExtractor` that are the central mechanisms for using pyHDLParser. + +.. code-block:: python + + vhdl_ex = vhdl.VhdlExtractor() + vlog_ex = vlog.VerilogExtractor() + + +VHDL +==== + +The VHDL parser can extract a variety of different objects from sourec code. +It can be used to access package definitions and component declarations,type and subtype definitions, functions, and +procedures found within a package. +It will not process entity declarations or nested subprograms and types. + +Extraction proceeds as follows: + +.. code-block:: python + + with io.open(fname, 'rt', encoding='latin-1') as fh: + code = fh.read() + vhdl_objs = vhdl_ex.extract_objects_from_source(code) + + vhdl_objs = vhdl_ex.extract_objects(fname) + +These will extract a list of all supported object types. +The result is a list of objects subclassed from :py:class:`~hdlparse.vhdl_parser.VhdlObject`. +You can pass an optional subclass of ``VhdlObject`` to filter the results for just that type. +Repeated calls are more efficient when using :py:meth:`~hdlparse.vhdl_parser.VhdlExtractor.extract_objects` which +maintains a cache of all previously parsed objects in the extractor. + +.. code-block:: vhdl + + package example is + component demo is + generic ( + GENERIC1: boolean := false; + GENERIC2: integer := 100 + ); + port ( + a, b : in std_ulogic := '1'; + c, d : out std_ulogic_vector(7 downto 0); + e, f : inout unsigned(7 downto 0) + ); + end component; + end package; + +Each port and generic is an instance of :py:class:`~hdlparse.vhdl_parser.VhdlParameter` containing the name, mode +(input, output, inout), and type. + +.. code-block:: python + + import hdlparse.vhdl_parser as vhdl + from hdlparse.vhdl_parser import VhdlComponent + + vhdl_ex = vhdl.VhdlExtractor() + vhdl_comps = vhdl_ex.extract_objects('example.vhdl', VhdlComponent) + + for c in vhdl_comps: + print('Component "{}":'.format(c.name)) + + print(' Generics:') + for p in c.generics: + print('\t{:20}{:8} {}'.format(p.name, p.mode, p.data_type)) + + print(' Ports:') + for p in c.ports: + print('\t{:20}{:8} {}'.format(p.name, p.mode, p.data_type )) + +When run against the example code produces the following: + +.. code-block: console + + Component "demo": + Generics: + GENERIC1 in boolean + GENERIC2 in integer + Ports: + a in std_ulogic + b in std_ulogic + c out std_ulogic_vector(7 downto 0) + d out std_ulogic_vector(7 downto 0) + e inout unsigned(7 downto 0) + f inout unsigned(7 downto 0) + + +VHDL arrays +----------- + +It can be useful to know which data types are an array. The :py:class:`~hdlparse.vhdl_parser.VhdlExtractor` class will +keep track of all visited array type definitions it sees. +The :py:meth:`~hdlparse.vhdl_parser.VhdlExtractor.is_array` method lets you query the internal list to check if a type +is for an array. +All IEEE standard array types are supported by default. +Any subtypes derived from an array type will also be considered as arrays. + +.. code-block:: python + + import hdlparse.vhdl_parser as vhdl + + vhdl_ex = vhdl.VhdlExtractor() + + code = ''' + package foobar is + type custom_array is array(integer range <>) of boolean; + subtype custom_subtype is custom_array(1 to 10); + end package; + ''' + vhdl_comps = vhdl_ex.extract_objects(code) + + # These all return true: + print(vhdl_ex.is_array('unsigned')) + print(vhdl_ex.is_array('custom_array')) + print(vhdl_ex.is_array('custom_subtype')) + +Parsed array data can be saved to a file with :py:meth:`~hdlparse.vhdl_parser.VhdlExtractor.save_array_types` and +restored with :py:meth:`~hdlparse.vhdl_parser.VhdlExtractor.load_array_types`. +This lets you parse one set of files for type definitions and use the saved info for parsing other code at a different +time. + + +Verilog +======= + +The Verilog parser is only able to extract module definitions with a port and optional parameter list. +Verilog modules are extracted using the :py:meth:`~hdlparse.verilog_parser.VerilogExtractor.extract_objects` and +:py:meth:`~hdlparse.verilog_parser.VerilogExtractor.extract_objects_from_source` methods. +The latter is used when you have the code in a string. +The former when you want to read the Veirlog source from a file. +When parsing a file, a cache of objects is maintained so you can repeatedly call +:py:meth:`~hdlparse.verilog_parser.VerilogExtractor.extract_objects` without reparsing the file. + +.. code-block:: python + + with open(fname, 'rt') as fh: + code = fh.read() + vlog_mods = vlog_ex.extract_objects_from_source(code) + + vlog_mods = vlog_ex.extract_objects(fname) + +The result is a list of extracted :py:class:`~hdlparse.verilog_parser.VerilogModule` objects. +Each instance of this class has ``name``, ``generics``, and ``ports`` attributes. +The ``name`` attribute is the name of the module. +The ``generics`` attribute is a list of extracted parameters and ``ports`` is a list of the ports on the module. + +.. code-block:: verilog + + module newstyle // This is a new style module def + #(parameter real foo = 8, bar=1, baz=2, + parameter signed [7:0] zip = 100) + ( + input x, x2, inout y, y2_long_output, + output wire [4:1] z, z2 + ); + endmodule + +Each port and generic is an instance of :py:class:`~hdlparse.verilog_parser.VerilogParameter` containing the name, mode +(input, output, inout), and type. + +.. code-block:: python + + import hdlparse.verilog_parser as vlog + + vlog_ex = vlog.VerilogExtractor() + vlog_mods = vlog_ex.extract_objects('example.v') + + for m in vlog_mods: + print('Module "{}":'.format(m.name)) + + print(' Parameters:') + for p in m.generics: + print('\t{:20}{:8}{}'.format(p.name, p.mode, p.data_type)) + + print(' Ports:') + for p in m.ports: + print('\t{:20}{:8}{}'.format(p.name, p.mode, p.data_type)) + + +When run against the example code produces the following: + +.. code-block:: console + + Module "newstyle": + Parameters: + foo in real + bar in real + baz in real + zip in signed [7:0] + Ports: + x input + x2 input + y inout + y2_long_output inout + z output wire [4:1] + z2 output wire [4:1] + + +Reference +========= + +.. automodule:: hdlparse + :members: + :undoc-members: + :show-inheritance: + +hdlparse\.minilexer +------------------- + +.. automodule:: hdlparse.minilexer + :members: + :undoc-members: + :show-inheritance: + +hdlparse\.verilog\_parser +------------------------- + +.. automodule:: hdlparse.verilog_parser + :members: + :undoc-members: + :show-inheritance: + +hdlparse\.vhdl\_parser +---------------------- + +.. automodule:: hdlparse.vhdl_parser + :members: + :undoc-members: + :show-inheritance: