python typing with new base model structure + reading user keywords i…

.github/workflows/build.yml

@@ -48,7 +48,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: ${{ matrix.python-version }}
+        python-version: '3.12'
 
     - name: Install Hatch
       run: pip install hatch
@@ -63,7 +63,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12"]
     steps:
     - name: Checkout Repository
       uses: actions/checkout@v4

.gitignore

@@ -12,4 +12,8 @@ image.png
 output_doc_robot.html
 devel.html
 build/**
-uv.lock
+uv.lock
+atest/output_classic.html
+atest/output_big.html
+results/
+oc_output.html

DEVELOPMENT.md

@@ -0,0 +1,101 @@
+# Development
+
+## Release Creation
+
+### Precondition
+
+- You are required to have an account for **[PyPi](https://pypi.org/)**.
+- Additionally, check that you have required permissions for the projects at ``PyPi & GitHub``!
+- Check that all pipeline-checks did pass, your code changes are ready and everything is already merged to the main branch!
+- Your local git configuration must work - check your authentication!
+
+### *Preferred* - Using Shell Script for Release Creation
+
+In the ``root directory`` of this repository you will find a script called ``create_release.sh``.
+When executing this script, it expects exactly one argument: the new name of the release / tag.
+Here you need to provide always the syntax ``X.X.X``, e.g. ``0.1.9``, ``0.5.0`` or ``1.0.0``.
+
+> [!TIP]
+> Please use following versioning to create ``alpha``, ``beta`` or ``releasecandidate`` release at ``PyPi``!    
+> Example:
+> ```bash
+> ./create_release.sh 1.0.0a1    # alpha
+> ./create_release.sh 1.0.0b2    # beta
+> ./create_release.sh 1.0.0rc1   # release candidate
+> ```
+
+The script will do two things automatically for you:
+1. Updating the version string in the **[\_\_about\_\_.py](src/testdoc/__about__.py)**
+2. Creating & Pushing a new tag to GitHub.
+
+Execute the following command to create a new release:
+```bash
+cd <project-root-directory>
+./create_release.sh 1.0.0
+```
+
+After executing the script, three pipeline jobs are getting triggered automatically:
+1. First job creates a new ``Release`` in github with the name of the created ``Tag``.
+2. Second job uploads the new wheel package to ``PyPi`` with the ``__version__`` from the ``__about__.py`` file.
+3. Third job generates a new keyword documentation via ``libdoc`` on the main branch, but pushes it to the ``gh_pages`` where it is available as public ``GitHub Page``.
+
+### *Backup* - Manual Version Bump & Tag Creation
+
+If the preferred way using the ``create_release.sh`` script does not work, you can also manually create a new release.
+Therefore, execute the following steps.
+
+#### 1. Increase Version
+
+Open the file **[\_\_about\_\_.py](src/testdoc/__about__.py)** and increase the version (``0.0.5 = major.minor.path``) before building & uploading the new python wheel package!
+
+The new version **must be unique** & **not already existing** in ``PyPi`` & ``GitHub Releases``!!!
+
+Commit & push the changed version into the ``main`` branch of the repository.
+
+#### 2. Create new Tag
+
+Now, create a new tag from the main branch with the syntax ``vX.X.X`` -> example: ``v1.0.5``.
+
+Use the following commands to create & push the tag:
+```
+git tag v0.0.5
+git push origin v0.0.5
+```
+
+#### 2.1. Creating GitHub Release & Deploy Wheel Package to PyPi
+
+After pushing the new tag, three pipeline jobs are getting triggered automatically:
+1. First job creates a new ``Release`` in github with the name of the created ``Tag``.
+2. Second job uploads the new wheel package to ``PyPi`` with the ``__version__`` from the ``__about__.py`` file.
+3. Third job generates a new keyword documentation via ``libdoc`` on the main branch, but pushes it to the ``gh_pages`` where it is available as public ``GitHub Page``.
+
+## Installing Dev Dependencies
+
+Contributing to this project & working with it locally, requires you to install some ``dev dependencies`` - use the following command in the project root directory:
+```
+pip install -e .[dev]
+```
+
+Afterwards, the library gets installed in ``editable mode`` & you will have a ``dev dependencies`` installed.
+
+## Hatch
+
+You will need the python package tool ``hatch`` for several operations in this repository.
+Hatch can be used to execute the linter, the tests or to build a wheel package.
+
+Use the following command:
+```shell
+pip install hatch
+```
+
+### Ececute Linting Checks via ruff
+
+```shell
+hatch run dev:lint
+```
+
+### Execute Acceptance Tests via PyTest
+
+```shell
+hatch run dev:atest
+```

README.md

@@ -81,6 +81,20 @@ testdoc --hide-source tests/ TestDocumentation.html
 testdoc --hide-keywords tests/ TestDocumentation.html
 ```
 
+## Visualization of Keywords
+
+Keywords are visualized in a specific design and to replicate the robot framework test case structure (model) as best as possible.
+
+### User / Library Keywords called in a Test Case Body
+
+This view does actually replicate the robot framework suite file with the ``*** Test Cases ***`` section, the ``Test Case Name`` and the ``Test Case Body``.
+
+![alt text](docs/test_keywords_visualization.png)
+
+### User Keyword defined in a Test Suite
+
+![alt text](docs/suite_keywords_visualization.png)
+
 ## Robot Framework Tags
 The commandline arguments ``include`` & ``exclude`` have more or less the same functionality like in the known ``robot ...`` command.     
 You can decide to weither include and / or exclude specific test cases into the test documentation.
@@ -138,6 +152,8 @@ border_color = "#CCCCCC"
 text_color = "#CCCCCC"
 title_color = "#00ffb9"
 robot_icon = "#00ffb9"
+code_area_background = "#303030"
+code_area_foreground = "#f1f1f1"
 ```
 
 ## HTML Template Selection
@@ -149,7 +165,7 @@ These template can be configured via ``cli arguments`` or within a ``.toml confi
 
 - v2
 
-### Available HTML Templates
+### Available HTML Templates - NOT RECOMMENDED
 
 You can choose one of the following designs:
 - v1
@@ -230,6 +246,8 @@ border_color = "#CCCCCC"
 text_color = "#CCCCCC"
 title_color = "#00ffb9"
 robot_icon = "#00ffb9"
+code_area_background = "#303030"
+code_area_foreground = "#f1f1f1"
 ```
 
 > [!TIP]
@@ -247,4 +265,8 @@ robot_icon = "#00ffb9"
 
 #### Robot / Default
 
-![alt text](docs/style_robot.png)
+![alt text](docs/style_robot.png)
+
+## Contribution & Development
+
+See [Development.md](./DEVELOPMENT.md) for more information about contributing & developing this library.

atest/second_test_cli.robot

@@ -0,0 +1,14 @@
+*** Settings ***
+Name    Suite 2
+Documentation    Basic Console Logging - Suite Doc
+Metadata    Author=Marvin Klerx
+Metadata    Creation=January 2026
+Test Tags    Global-Tag
+
+
+*** Test Cases ***
+Suite 2 - TC-001
+    [Documentation]    Basic Console Logging
+    [Tags]    RobotTestDoc
+
+    Log    Log message in suite 2 - TC-001

atest/test_cli.py

@@ -12,12 +12,23 @@ def test_cli_help():
 def test_cli_cmd():
     current_dir = os.path.dirname(os.path.abspath(__file__))
     robot = os.path.join(current_dir, "test_cli.robot")
-    output = os.path.join(current_dir, "output.html")
+    output = os.path.join(current_dir, "output_classic.html")
     runner = CliRunner()
     result = runner.invoke(main, [robot, output])
     assert result.exit_code == 0
     assert "Generated" in result.output
-    assert "output.html" in result.output
+    assert "output_classic.html" in result.output
+    assert os.path.exists(output)
+
+def test_cli_cmd_big_suite():
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    robot = os.path.join(current_dir)
+    output = os.path.join(current_dir, "output_big.html")
+    runner = CliRunner()
+    result = runner.invoke(main, [robot, output])
+    assert result.exit_code == 0
+    assert "Generated" in result.output
+    assert "output_big.html" in result.output
     assert os.path.exists(output)
 
 

atest/test_cli.robot

@@ -9,4 +9,18 @@ Test Tags    Global-Tag
 Log Message
     [Documentation]    Basic Console Logging
     [Tags]    RobotTestDoc
-    Log    RobotFramework Test Documentation Generator!
+
+    # this is my commentary
+    Log    RobotFramework Test Documentation Generator!
+
+
+*** Keywords ***
+MyUserKeword
+    [Documentation]    User Keyword
+
+    Log   This is a user keyword
+
+My Second User Keyword
+    [Documentation]    User Keyword
+
+    Log   This is a user keyword

atest/testcases/component_a/suite_a.robot

@@ -0,0 +1,14 @@
+*** Test Cases ***
+Suite A - TC-001
+    [Tags]    CompA    Regression
+    Log    A-TC001
+
+Suite A - TC002
+    [Tags]    CompA    Smoke
+    Log    A-TC002
+
+
+*** Keywords ***
+Suite A - User Keyword A
+    [Documentation]    docs
+    Log    A-KW001

atest/testcases/component_b/subcomponent_b/subsuite_b.robot

@@ -0,0 +1,14 @@
+*** Test Cases ***
+Subsuite B - TC-001
+    [Tags]    CompB    Regression
+    Log    SB-TC001
+
+Subsuite B - TC002
+    [Tags]    CompB    Smoke    Feature-XYZ
+    Log    SB-TC002
+
+
+*** Keywords ***
+Subsuite B - User Keyword B
+    [Documentation]    docs
+    Log    SB-KW001

atest/testcases/component_b/suite_b.robot

@@ -0,0 +1,20 @@
+*** Settings ***
+Name    Custom Name Suite B
+Metadata    author=Marvin Klerx
+Metadata    creation_date=January 2026
+Metadata    company=imbus AG
+
+
+*** Test Cases ***
+Suite C - TC001
+    [Tags]    CompC    robot:exclude
+    Log    C-TC001
+
+Suite C - TC002
+    [Tags]    CompC    test:retry(1)
+    Log    C-TC002
+
+
+*** Keywords ***
+Suite C - User Keyword 1
+    Log    Suite C - User Keyword 1

pyproject.toml

@@ -7,7 +7,7 @@ name = "robotframework-testdoc"
 dynamic = ["version"]
 description = "A CLI Tool to generate a Test Documentation for your RobotFramework Test Scripts."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
     { name = "Marvin Klerx", email = "marvinklerx20@gmail.com" }
 ]
@@ -16,7 +16,6 @@ license = { text = "Apache-2.0" }
 classifiers = [
   "Development Status :: 4 - Beta",
   "Programming Language :: Python",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12"
@@ -26,7 +25,8 @@ dependencies = [
     "click",
     "robotframework",
     "jinja2",
-    "tomli"
+    "tomli",
+    "pydantic"
 ]
 
 [project.optional-dependencies]

src/testdoc/html/rendering/render.py

@@ -1,6 +1,8 @@
 from jinja2 import Environment, FileSystemLoader
 import os
 
+from ...parser.models import SuiteInfoModel
+
 from ...html.themes.theme_config import ThemeConfig
 from ...helper.cliargs import CommandLineArguments
 from ...helper.datetimeconverter import DateTimeConverter
@@ -26,7 +28,7 @@ def _html_templ_selection(self):
             raise ValueError(f"CLI Argument 'html_template' got value '{self.args.html_template}' - value not known!")         
 
     def render_testdoc(self,
-            suites,
+            suites: list[SuiteInfoModel],
             output_file
         ):
         env = Environment(loader=FileSystemLoader(self.TEMPLATE_DIR))