✨ Initial implementation

.github/actions/setup_rye/action.yml

@@ -0,0 +1,31 @@
+name: Set up rye
+runs:
+  using: 'composite'
+  steps:
+    # rye uses uv under the hood, so we need to set the cache directory correctly, based on the OS
+    - name: Set UV_CACHE_DIR for Linux
+      if: runner.os == 'Linux'
+      run: |
+        echo "UV_CACHE_DIR=/home/runner/.cache/uv" >> $GITHUB_ENV
+      shell: bash
+    - name: Set MATURIN_PEP517_ARGS for Linux
+      if: runner.os == 'Linux'
+      # make sure we always use zig, to get manylinux2014 compatible rust binaries
+      run: |
+        echo "MATURIN_PEP517_ARGS=--zig" >> $GITHUB_ENV
+      shell: bash
+    - name: Set UV_CACHE_DIR for MacOS
+      if: runner.os == 'macOS'
+      run: echo "UV_CACHE_DIR=/Users/gh-runner/Library/Caches/uv" >> $GITHUB_ENV
+      shell: bash
+    - name: Set UV_CACHE_DIR for Windows
+      if: runner.os == 'Windows'
+      run: echo "UV_CACHE_DIR=C:\\Users\\useblocks\\AppData\\Local\\uv-${{ runner.name }}" >> $env:GITHUB_ENV
+      shell: pwsh
+    # now install rye and sync the dependencies
+    - uses: eifinger/setup-rye@v4
+      with:
+        version: "0.42.0"
+        enable-cache: false
+    - run: rye sync
+      shell: ${{ runner.os == 'Windows' && 'powershell' || 'bash' }}

.github/workflows/ci.yml

@@ -0,0 +1,93 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+*"
+  pull_request:
+    types: [closed, labeled, reopened, unlabeled, synchronize, opened]
+
+concurrency:
+  # For PRs, cancel in progress runs, if a new commit is pushed
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# These permissions are needed to interact with GitHub's OIDC Token endpoint.
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  pre-commit:
+    name: Pre-commit
+    runs-on: [self-hosted, linux, x64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - run: python -m pip install pre-commit pre-commit-uv
+      # - uses: pre-commit/action@v3.0.1  # note we don't use this, since it calls ations/cache, which actually takes longer than without it
+      - run: pre-commit run --all --show-diff-on-failure --color=always
+
+  mypy:
+    name: MyPy
+    runs-on: [self-hosted, linux, x64]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup_rye
+      - run: rye run mypy:all
+
+  pytest:
+    name: Pytest (${{ matrix.os }}-${{ matrix.arch }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: linux
+            arch: x64
+          - os: linux
+            arch: arm64
+          - os: windows
+            arch: x64
+          - os: macos
+            arch: arm64
+
+    runs-on: [self-hosted, "${{ matrix.os }}", "${{ matrix.arch }}"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup_rye
+      - run: rye test -a
+
+  docs:
+    name: Documentation build
+    runs-on: [self-hosted, linux, x64]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup_rye
+      - name: Run documentation build
+        run: rye run docs
+
+  all_good:
+    # This job does nothing and is only used for the branch protection
+    # see https://github.com/marketplace/actions/alls-green#why
+
+    if: ${{ !cancelled() }}
+
+    needs:
+      - pre-commit
+      - mypy
+      - pytest
+      - docs
+
+    runs-on: [self-hosted, linux, x64]
+
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}

.github/workflows/gh_pages.yml

@@ -0,0 +1,53 @@
+# Workflow for building and deploying the Sphinx site to GitHub Pages
+#
+name: Deploy docs to GH Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build
+    runs-on: [self-hosted, linux, x64]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - uses: eifinger/setup-rye@v4
+      - run: rye sync
+      - name: Run documentation build
+        run: rye run docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: [self-hosted, linux, x64]
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yaml

@@ -0,0 +1,53 @@
+name: Release
+on:
+  push:
+    tags:
+      - '[0-9].[0-9]+.[0-9]+'
+
+permissions:
+    id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    contents: read
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,21 @@
+# python generated files
+.ruff_cache
+.pytest_cache
+.mypy_cache
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.venv
+
+# lock files
+requirements.lock
+requirements-dev.lock
+
+# Sphinx build output
+**/_build
+
+# rye is the primary tool, uv is only used for on-the-fly setups
+uv.lock

.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.2
+    hooks:
+      - id: ruff-format
+        name: python format
+      - id: ruff
+        alias: ruff-check
+        name: python lint
+        args: [--fix]
+
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: taplo-format
+      # lint fetches schemas online at each call, deactivate for now
+      - id: taplo-lint

.python-version

@@ -0,0 +1 @@
+3.12.7

README.md

@@ -1,8 +1,37 @@
-* [ ] Move code
-* [ ] Create doc project, be based on ubCode/ubTrace
-* [ ] ubCode ubproject.toml
-* [ ] CI for docs and tests
-* [ ] DNS for codelinks.useblocks.com
-* [ ] Deployment on pypi (see Sphinx-Needs)
-* [ ] Repo rules (no main pushes / branch protection)
-* [ ] Cleanup ubTrace (files, ci, rye commands)
+# Sphinx CodeLinks
+
+A Sphinx extension for discovering, linking, and documenting source code across projects.
+
+## Features
+
+- **Source Discovery**: Automatically discover source files in your project
+- **Virtual Documentation**: Generate documentation from code without modifying source files
+- **Code Linking**: Create intelligent links between code elements
+- **Sphinx Integration**: Seamless integration with existing Sphinx documentation
+
+## Quick Start
+
+```bash
+pip install sphinx-codelinks
+```
+
+Add to your `conf.py`:
+
+```python
+extensions = ['sphinx_needs', 'sphinx_codelinks']
+```
+
+## Documentation
+
+Full documentation: https://codelinks.useblocks.com
+
+## Components
+
+- **Source Discovery** ([`src/sphinx_codelinks/source_discovery`](src/sphinx_codelinks/source_discovery)): Code analysis and discovery
+- **Virtual Docs** ([`src/sphinx_codelinks/virtual_docs`](src/sphinx_codelinks/virtual_docs)): Documentation generation
+- **Sphinx Extension** ([`src/sphinx_codelinks/sphinx_extension`](src/sphinx_codelinks/sphinx_extension)): Sphinx integration
+- **Command Line** ([`src/sphinx_codelinks/cmd.py`](src/sphinx_codelinks/cmd.py)): CLI interface
+
+## Development
+
+See [Development Guide](docs/source/development/) for contributing guidelines.

docs/conf.py

@@ -0,0 +1,67 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+from datetime import datetime
+from pathlib import Path
+import tomllib
+
+_project_data = tomllib.loads(
+    (Path(__file__).parent.parent / "pyproject.toml").read_text("utf8")
+)["project"]
+
+project = _project_data["name"]
+author = _project_data["authors"][0]["name"]
+copyright = f"{datetime.now().year}, {author}"
+version = release = _project_data["version"]
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx_design",
+    "sphinx_needs",
+    "sphinx_codelinks",
+    "sphinx.ext.intersphinx",
+    "sphinx_code_tabs",
+    "sphinxcontrib.typer",
+]
+
+# exclude_patterns = []
+templates_path = ["_templates"]
+show_warning_types = True
+
+todo_include_todos = True
+
+# -- Options for intersphinx extension ---------------------------------------
+
+intersphinx_mapping = {
+    "needs": ("https://sphinx-needs.readthedocs.io/en/latest/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_title = "CodeLinks"
+html_theme = "furo"
+# original source is in ubdocs repo at docs/developer_handbook/design/files/ubcode_favicon/favicon.ico
+html_favicon = "source/_static/favicon.ico"
+html_static_path = ["source/_static"]
+
+html_theme_options = {
+    "sidebar_hide_name": True,
+    "top_of_page_buttons": ["view", "edit"],
+    "source_repository": "https://github.com/useblocks/sphinx-codelinks",
+    "source_branch": "main",
+    "source_directory": "docs/source/",
+    "light_logo": "sphinx-codelinks-logo_dark.svg",
+    "dark_logo": "sphinx-codelinks-logo_light.svg",
+}
+html_css_files = ["furo.css"]
+
+src_trace_config_from_toml = "./src_trace.toml"