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"