README: Extract Python code example to 'example.py' and run it

readme: move example to 'example.py' and update it

Author: Paebbels

.github/workflows/Pipeline.yml

@@ -222,31 +222,84 @@ jobs:
         run: |
           twine upload dist/*
 
+  VerifyDocs:
+    name: 📓 Verify that example(s) is/are runnable
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v2
+
+      - name: '⚙️ Setup GHDL'
+        uses: ghdl/setup-ghdl-ci@master
+
+      - name: '🐍 Setup Python'
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: '🐍 Install dependencies'
+        run: |
+          pip3 install pytest
+          pip3 install git+https://github.com/ghdl/ghdl.git@$(ghdl version hash)
+      
+      - name: 'Extract example from README'
+        shell: python
+        run: |
+          from pathlib import Path
+          import re
+
+          ROOT = Path('.')
+
+          with (ROOT / 'README.md').open('r') as rptr:
+              content = rptr.read()
+          
+          m = re.search(r"```py(thon)?(?P<code>.*?)```", content, re.MULTILINE|re.DOTALL)
+          
+          if m is None:
+              raise Exception("Regular expression did not find the example in the README!")
+          
+          with (ROOT / 'tests/docs/example.py').open('w') as wptr:
+              wptr.write(m["code"])
+      
+      - name: 'Print example.py'
+        run: cat tests/docs/example.py
+
+      - name: 'Run example.py'
+        run: |
+          cd tests/docs
+          python3 example.py
+
+
   BuildTheDocs:
     name: 📓 Run BuildTheDocs and publish to GH-Pages
     runs-on: ubuntu-latest
+
+    needs:
+      - VerifyDocs
+      
     steps:
 
-    - name: Checkout repository
-      uses: actions/checkout@v2
+      - name: Checkout repository
+        uses: actions/checkout@v2
 
-    - name: 🚢 Build documentation in 'pyVHDLModel/doc'
-      run: |
-        docker build -t vhdl/doc - <<-EOF
-        FROM btdi/sphinx:featured
-        RUN apk add -U --no-cache graphviz
-        EOF
+      - name: 🚢 Build container image 'vhdl/doc'
+        run: |
+          docker build -t vhdl/doc - <<-EOF
+          FROM btdi/sphinx:featured
+          RUN apk add -U --no-cache graphviz
+          EOF
 
-    - name: 🛳️ Unknown
-      uses: buildthedocs/btd@v0
-      with:
-        token: ${{ github.token }}
+      - name: 🛳️ Build documentation in 'pyVHDLModel/doc'
+        uses: buildthedocs/btd@v0
+        with:
+          token: ${{ github.token }}
 
-    - name: Upload artifacts to GitHub Pages
-      uses: actions/upload-artifact@master
-      with:
-        name: doc
-        path: doc/_build/html
+      - name: Upload artifacts to GitHub Pages
+        uses: actions/upload-artifact@master
+        with:
+          name: doc
+          path: doc/_build/html
 
   ArtifactCleanUp:
     name: 🗑️ Artifact Cleanup
@@ -260,8 +313,8 @@ jobs:
       ARTIFACT: ${{ needs.Package.outputs.artifact }}
 
     steps:
-    - name: 🗑️ Delete all Artifacts
-      uses: geekyeggo/delete-artifact@v1
-      with:
-        name: |
-          ${{ env.ARTIFACT }}
+      - name: 🗑️ Delete all Artifacts
+        uses: geekyeggo/delete-artifact@v1
+        with:
+          name: |
+            ${{ env.ARTIFACT }}

README.md

@@ -57,21 +57,21 @@ from pyGHDL.dom.NonStandard import Design, Document
 sourceFile = Path("example.vhdl")
 
 design = Design()
-library = Design.GetLibrary("lib")
+library = design.GetLibrary("lib")
 document = Document(sourceFile)
 design.AddDocument(document, library)
 
 for entity in document.Entities:
-  print("{}".format(entity.Name))
+  print("{}".format(entity.Identifier))
   print("  generics:")
-  for generic in entity.Generics:
+  for generic in entity.GenericItems:
     print("  - {} : {!s} {}".format(
-      generic.Identifier, generic.Mode, generic.SubTypeIndication)
+      generic.Identifier, generic.Mode, generic.Subtype)
     )
   print("  ports:")
-  for port in entity.Ports:
+  for port in entity.PortItems:
     print("  - {} : {!s} {}".format(
-      port.Identifier, port.Mode, port.SubTypeIndication)
+      port.Identifier, port.Mode, port.Subtype)
     )
 ```
 

tests/docs/example.vhdl

@@ -0,0 +1,32 @@
+library ieee;
+use     ieee.std_logic_1164.all;
+use     ieee.numeric_std.all;
+
+entity entity_1 is
+	generic (
+		FREQ : real     := (100.0 * 1024.0 * 1024.0);
+		BITS : positive := 8
+	);
+	port (
+	  Clock: in  std_logic;
+	  Reset: in  std_logic := '0';
+	  Q:     out std_logic_vector(BITS - 1 downto 0)
+	);
+end entity entity_1;
+
+architecture behav of entity_1 is
+	signal Reset_n : std_logic;
+begin
+	Reset_n <= (not Reset);
+
+	process(Clock)
+	begin
+		if rising_edge(Clock) then
+			if Reset_n = '0' then
+				Q <= (others => '0');
+			else
+				Q <= std_logic_vector(unsigned(Q) + 1);
+			end if;
+		end if;
+	end process;
+end architecture behav;