Merge pull request #11 from VHDL/dev

More documentation

.github/workflows/Release.yml

@@ -11,7 +11,8 @@ jobs:
  env:
  PYTHON: ${{ github.event.client_payload.PYTHON }}
  steps:
- - uses: actions/checkout@v2
+ - name: Checkout repository
+ uses: actions/checkout@v2
  with:
  ref: ${{ github.event.client_payload.ref }}
 

.github/workflows/Test.yml

@@ -15,7 +15,8 @@ jobs:
  env:
  PYTHON: ${{ matrix.python-version }}
  steps:
- - uses: actions/checkout@v2
+ - name: Checkout repository
+ uses: actions/checkout@v2
 
  - name: Setup Python ${{ matrix.python-version }}
  uses: actions/setup-python@v2
@@ -38,7 +39,8 @@ jobs:
  env:
  PYTHON: 3.9
  steps:
- - uses: actions/checkout@v2
+ - name: Checkout repository
+ uses: actions/checkout@v2
 
  - name: Setup Python ${{ env.PYTHON }}
  uses: actions/setup-python@v2

.gitignore

@@ -2,14 +2,16 @@
 __pycache__/
 *.py[cod]
 
-# Python installation packages
-dist/
-
 # Coverage.py
 .coverage
 .cov
 coverage.xml
 
+# setuptools
+/build
+/dist
+/*.egg-info
+
 # Sphinx
 doc/_build/
 doc/pyVHDLModel/**/*.*

doc/LanguageModel/DesignUnits.rst

@@ -3,41 +3,58 @@
 Design Units
 ############
 
-* Primary Units
+A VHDL design (see :ref:`vhdlmodel-design`) is assembled from *design units*. VHDL distinguishes
+between *primary* and *secondary* design units.
 
- * Context
- * Configuration
- * Entity
- * Package
+.. rubric:: Table of Content
 
-* Secondary Units
+* :ref:`vhdlmodel-primary`
 
- * Architeture
- * Package Body
+ * :ref:`vhdlmodel-context`
+ * :ref:`vhdlmodel-configuration`
+ * :ref:`vhdlmodel-entity`
+ * :ref:`vhdlmodel-package`
+
+* :ref:`vhdlmodel-secondary`
+
+ * :ref:`vhdlmodel-architeture`
+ * :ref:`vhdlmodel-packagebody`
+
+
+.. _vhdlmodel-primary:
 
 Primary Units
 =============
 
+.. _vhdlmodel-context:
+
 Context
 -------
 
 .. todo::
 
  Write documentation.
 
+
+
+.. _vhdlmodel-configuration:
+
 Configuration
 -------------
 
 .. todo::
 
  Write documentation.
 
+
+
+.. _vhdlmodel-entity:
+
 Entity
 ------
 
-.. todo::
-
- Write documentation.
+An ``Entity`` represents a VHDL entity declaration. It has a list of generic and
+port items. It can contain a list of declared and body items.
 
 **Condensed definition of class** :class:`~pyVHDLModel.VHDLModel.Entity`:
 
@@ -46,7 +63,7 @@ Entity
  @export
  class Entity(PrimaryUnit):
  _libraryReferences: List[LibraryReference]
- _uses: List[Use]
+ _packageReferences: List[PackageReference]
  _genericItems: List[GenericInterfaceItem]
  _portItems: List[PortInterfaceItem]
  _declaredItems: List # FIXME: define liste element type e.g. via Union
@@ -58,7 +75,7 @@ Entity
  def LibraryReferences(self) -> List[LibraryReference]:
 
  @property
- def Uses(self) -> List[Use]:
+ def PackageReferences(self) -> List[PackageReference]:
 
  @property
  def GenericItems(self) -> List[GenericInterfaceItem]:
@@ -74,6 +91,8 @@ Entity
 
 
 
+.. _vhdlmodel-package:
+
 Package
 -------
 
@@ -88,7 +107,7 @@ Package
  @export
  class Package(PrimaryUnit):
  _libraryReferences: List[Library]
- _uses: List[Use]
+ _packageReferences: List[PackageReference]
  _genericItems: List[GenericInterfaceItem]
  _declaredItems: List
 
@@ -98,7 +117,7 @@ Package
  def LibraryReferences(self) -> List[Library]:
 
  @property
- def Uses(self) -> List[Use]:
+ def PackageReferences(self) -> List[PackageReference]:
 
  @property
  def GenericItems(self) -> List[GenericInterfaceItem]:
@@ -108,9 +127,13 @@ Package
 
 
 
+.. _vhdlmodel-secondary:
+
 Secondary Units
 ===============
 
+.. _vhdlmodel-architeture:
+
 Architeture
 -----------
 
@@ -126,7 +149,7 @@ Architeture
  class Architecture(SecondaryUnit):
  _entity: Entity
  _libraryReferences: List[Library]
- _uses: List[Use]
+ _packageReferences: List[PackageReference]
  _declaredItems: List # FIXME: define liste element type e.g. via Union
  _bodyItems: List['ConcurrentStatement']
 
@@ -139,7 +162,7 @@ Architeture
  def LibraryReferences(self) -> List[Library]:
 
  @property
- def Uses(self) -> List[Use]:
+ def PackageReferences(self) -> List[PackageReference]:
 
  @property
  def DeclaredItems(self) -> List:
@@ -149,6 +172,8 @@ Architeture
 
 
 
+.. _vhdlmodel-packagebody:
+
 Package Body
 ------------
 
@@ -164,7 +189,7 @@ Package Body
  class PackageBody(SecondaryUnit):
  _package: Package
  _libraryReferences: List[Library]
- _uses: List[Use]
+ _packageReferences: List[PackageReference]
  _declaredItems: List
 
  def __init__(self, name: str):
@@ -176,7 +201,7 @@ Package Body
  def LibraryReferences(self) -> List[Library]:
 
  @property
- def Uses(self) -> List[Use]:
+ def PackageReferences(self) -> List[PackageReference]:
 
  @property
  def DeclaredItems(self) -> List:

doc/LanguageModel/Enumerations.rst

@@ -3,16 +3,30 @@
 Enumerations
 ############
 
+The language model contains some enumerations to express a *kind* of a models entity.
 
-Modes
-=====
+.. rubric:: Table of Content
+
+* :ref:`vhdlmodel-mode`
+* :ref:`vhdlmodel-objclass`
+
+
+
+.. _vhdlmodel-mode:
+
+Mode
+====
 
 .. todo::
 
  Write documentation.
 
-Object Classes
-==============
+
+
+.. _vhdlmodel-objclass:
+
+Object Class
+============
 
 .. todo::
 

doc/LanguageModel/Miscellaneous.rst

@@ -3,10 +3,17 @@
 Concepts not defined by VHDL
 ############################
 
-Some features required for a holistic language model are not defined in
-the VHDL :term:`LRM` (IEEE Std. 1076) or made explicitly implementation
+Some features required for a holistic language model are not defined in the VHDL
+:term:`LRM` (IEEE Std. 1076). Other features made explicitly implementation
 specific to the implementer.
 
+.. rubric:: Table of Content
+
+* :ref:`vhdlmodel-design`
+* :ref:`vhdlmodel-library`
+* :ref:`vhdlmodel-document`
+
+
 .. _vhdlmodel-design:
 
 Design
@@ -72,20 +79,21 @@ is a *primary* design unit like: ``configuration``, ``entity``, ``package`` or
 
 
 
-.. _vhdlmodel-sourcefile:
+.. _vhdlmodel-document:
 
-Sourcecode File
-===============
+Document
+========
 
-A source file contains multiple *design units*. Each design unit listed in a
-sourcecode file is a *primary* or `secondary`design unit like: ``configuration``,
-``entity``, ``architecture``, ``package``, ``package body`` or ``context``.
+A source file (document) contains multiple *design units*. Each design unit
+listed in a sourcecode file is a *primary* or *secondary* design unit like:
+``configuration``, ``entity``, ``architecture``, ``package``, ``package body``
+or ``context``.
 
 Design unit may be preceded by a context made of ``library``, ``use`` and
-``context`` statements. These statements are not directly visible in the ``Document``
-object, because design unit contexts are consumed by the design units. See the
-``Libraries`` and ``Uses`` fields of each design unit to investigate the consumed
-contexts.
+``context`` statements. These statements are not directly visible in the
+``Document`` object, because design unit contexts are consumed by the design
+units. See the ``Libraries`` and ``Uses`` fields of each design unit to
+investigate the consumed contexts.
 
 **Condensed definition of class** :class:`~pyVHDLModel.VHDLModel.Document`:
 

doc/LanguageModel/SubprogramDefinitions.rst

@@ -3,8 +3,14 @@
 Subprogram Declarations
 ########################
 
-* Procedure
-* Function
+.. rubric:: Table of Content
+
+* :ref:`vhdlmodel-procedure`
+* :ref:`vhdlmodel-function`
+
+
+
+.. _vhdlmodel-procedure:
 
 Procedure
 =========
@@ -13,6 +19,10 @@ Procedure
 
  Write documentation.
 
+
+
+.. _vhdlmodel-function:
+
 Function
 ========
 

doc/LanguageModel/index.rst

@@ -3,7 +3,20 @@
 VHDL Language Model
 ###################
 
+.. topic:: Design Goal
+
+ * Clearly named classes that model the semantics of VHDL.
+ * All language constructs (statements, declarations, specifications, …) have
+ their own classes. |br| These classes are arranged in a logical hierarchy,
+ with a single common base-class.
+ * Child objects shall have a reference to their parent.
+ * Comments will be associated with a particular code object.
+ * Easy modifications of the object tree.
+
+.. rubric:: Elements of the Language Model
+
 .. toctree::
+ :maxdepth: 1
 
  Miscellaneous
  Enumerations

doc/conf.py

@@ -37,7 +37,7 @@ def _LatestTagName():
 
 # The full version, including alpha/beta/rc tags
 version = "0.8" # The short X.Y version.
-release = "0.8.0" # The full version, including alpha/beta/rc tags.
+release = "0.8.1" # The full version, including alpha/beta/rc tags.
 try:
  if _IsUnderGitControl:
  latestTagName = _LatestTagName()[1:] # remove prefix "v"