feat: add codelinks example

.github/workflows/ci.yml

@@ -80,6 +80,41 @@ jobs:
                require_tests: true
                check_name: "Test Results (Windows)"
 
+    test-on-macos:
+        name: Build and Test on macOS
+        runs-on: macos-latest
+        needs:
+            - lint
+        timeout-minutes: 15
+        steps:
+            - uses: actions/checkout@v6
+              with:
+                  fetch-depth: 0
+
+            - name: Setup Python
+              uses: actions/setup-python@v6
+              with:
+                  python-version: "3.13"
+
+            - name: Install uv
+              uses: astral-sh/setup-uv@v6
+
+            - name: install tools, build and test
+              run: |
+                ./build.sh
+
+            - name: Publish Test Report
+              if: always()
+              uses: mikepenz/action-junit-report@v6
+              with:
+               report_paths: "./build/test-report.xml"
+               detailed_summary: true
+               include_passed: true
+               fail_on_failure: true
+               fail_on_parse_error: true
+               require_tests: true
+               check_name: "Test Results (macOS)"
+
     test-on-linux:
         name: Build and Test on Linux
         runs-on: ubuntu-24.04
@@ -121,6 +156,7 @@ jobs:
             - lint
             - test-on-windows
             - test-on-linux
+            - test-on-macos
 
         runs-on: ubuntu-24.04
         environment: release

docs/codelinks.toml

@@ -0,0 +1,23 @@
+[codelinks]
+# Configuration for source tracing
+set_local_url = true            # Set to true to enable local code html and URL generation
+local_url_field = "local-url"   # Need's field name for local URL
+set_remote_url = true           # Set to true to enable remote url to be generated
+remote_url_field = "remote-url" # Need's field name for remote URL
+
+[codelinks.projects.srcpy]
+remote_url_pattern = "https://github.com/avengineers/hammocking/blob/{commit}/{path}#L{line}"
+
+[codelinks.projects.srcpy.source_discover]
+src_dir = "../src/hammocking"
+include = ["**/*.py"]
+comment_type = "python"
+
+[codelinks.projects.srcpy.analyse.oneline_comment_style]
+# Fields that are defined in the oneline comment style
+needs_fields = [
+    { "name" = "title", "type" = "str" },
+    { "name" = "id", "type" = "str" },
+    { "name" = "type", "type" = "str", "default" = "impl" },
+    { "name" = "links", "type" = "list[str]", "default" = [] },
+]

docs/conf.py

@@ -75,3 +75,10 @@
 
 html_theme = "sphinx_rtd_theme"
 # html_static_path = ["_static"]
+
+# sphinx_needs
+extensions.append("sphinx_codelinks")
+
+# https://codelinks.useblocks.com/components/configuration.html
+
+src_trace_config_from_toml = "codelinks.toml"

docs/index.md

@@ -11,4 +11,5 @@ design
 installation
 usage
 contribution
+source_link
 ```

docs/source_link.rst

@@ -0,0 +1,10 @@
+Codelinks
+#########
+
+Needs elements from source code.
+
+.. impl:: HammockIni Spec
+   :id: IMPL_HammockIniSpec
+
+.. src-trace::
+   :project: srcpy

pyproject.toml

@@ -5,7 +5,7 @@ description = "Create mocks for c-code automatically"
 authors = [{ name = "Avengineers", email = "karsten.guenther@kamg.de" }]
 license = { text = "MIT" }
 readme = "README.md"
-requires-python = ">=3.10,<3.14"
+requires-python = ">=3.12,<3.14"
 classifiers = [
     "Development Status :: 2 - Pre-Alpha",
     "Intended Audience :: Developers",
@@ -47,6 +47,7 @@ dev = [
     "mlx-traceability>=10.0,<11",
     "sphinx-book-theme>=1.1,<2",
     "sphinx-design>=0.5,<1",
+    "sphinx-codelinks>=1.2.0,<2"
 ]
 
 [tool.semantic_release]

src/hammocking/hammocking.py

@@ -23,6 +23,7 @@
 from py_app_dev.core.subprocess import SubprocessExecutor
 
 
+# @ HammockIni, IMPL_HammockIni, impl, [IMPL_HammockIniSpec]
 @dataclass
 class HammockIni(DataClassDictMixin):
     """Configuration for Hammock Ini File"""

tests/test_hammocking.py

@@ -728,6 +728,8 @@ def test_init(self, tmp_path: Path) -> None:
 # nm=nm
 # include_pattern=....
 exclude_pattern=^(_|llvm_|memcmp|memcpy|memset|bzero|exp|strlen)
+[hammocking.darwin]
+ignore_path=some_include_dir
 [hammocking.linux]
 ignore_path=some_include_dir
 clang_lib_file=libclang.so