Skip to content

Commit 514f13c

Browse files
juiwenchenubmarco
juiwenchen
and
ubmarco
authored
✨ Initial implementation (#1)
--------- Co-authored-by: Marco Heinemann <marco.heinemann@useblocks.com>
1 parent 66b8768 commit 514f13c

69 files changed

Lines changed: 5945 additions & 8 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/actions/setup_rye/action.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Set up rye
2+
runs:
3+
using: 'composite'
4+
steps:
5+
# rye uses uv under the hood, so we need to set the cache directory correctly, based on the OS
6+
- name: Set UV_CACHE_DIR for Linux
7+
if: runner.os == 'Linux'
8+
run: |
9+
echo "UV_CACHE_DIR=/home/runner/.cache/uv" >> $GITHUB_ENV
10+
shell: bash
11+
- name: Set MATURIN_PEP517_ARGS for Linux
12+
if: runner.os == 'Linux'
13+
# make sure we always use zig, to get manylinux2014 compatible rust binaries
14+
run: |
15+
echo "MATURIN_PEP517_ARGS=--zig" >> $GITHUB_ENV
16+
shell: bash
17+
- name: Set UV_CACHE_DIR for MacOS
18+
if: runner.os == 'macOS'
19+
run: echo "UV_CACHE_DIR=/Users/gh-runner/Library/Caches/uv" >> $GITHUB_ENV
20+
shell: bash
21+
- name: Set UV_CACHE_DIR for Windows
22+
if: runner.os == 'Windows'
23+
run: echo "UV_CACHE_DIR=C:\\Users\\useblocks\\AppData\\Local\\uv-${{ runner.name }}" >> $env:GITHUB_ENV
24+
shell: pwsh
25+
# now install rye and sync the dependencies
26+
- uses: eifinger/setup-rye@v4
27+
with:
28+
version: "0.42.0"
29+
enable-cache: false
30+
- run: rye sync
31+
shell: ${{ runner.os == 'Windows' && 'powershell' || 'bash' }}

‎.github/workflows/ci.yml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
name: ci
2+
3+
on:
4+
push:
5+
branches: [main]
6+
tags:
7+
- "v[0-9]+.[0-9]+.[0-9]+*"
8+
pull_request:
9+
types: [closed, labeled, reopened, unlabeled, synchronize, opened]
10+
11+
concurrency:
12+
# For PRs, cancel in progress runs, if a new commit is pushed
13+
group: ${{ github.workflow }}-${{ github.ref }}
14+
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
15+
16+
# These permissions are needed to interact with GitHub's OIDC Token endpoint.
17+
permissions:
18+
id-token: write
19+
contents: read
20+
21+
jobs:
22+
pre-commit:
23+
name: Pre-commit
24+
runs-on: [self-hosted, linux, x64]
25+
steps:
26+
- uses: actions/checkout@v4
27+
- uses: actions/setup-python@v5
28+
with:
29+
python-version-file: ".python-version"
30+
- run: python -m pip install pre-commit pre-commit-uv
31+
# - 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
32+
- run: pre-commit run --all --show-diff-on-failure --color=always
33+
34+
mypy:
35+
name: MyPy
36+
runs-on: [self-hosted, linux, x64]
37+
38+
steps:
39+
- uses: actions/checkout@v4
40+
- uses: ./.github/actions/setup_rye
41+
- run: rye run mypy:all
42+
43+
pytest:
44+
name: Pytest (${{ matrix.os }}-${{ matrix.arch }})
45+
strategy:
46+
fail-fast: false
47+
matrix:
48+
include:
49+
- os: linux
50+
arch: x64
51+
- os: linux
52+
arch: arm64
53+
- os: windows
54+
arch: x64
55+
- os: macos
56+
arch: arm64
57+
58+
runs-on: [self-hosted, "${{ matrix.os }}", "${{ matrix.arch }}"]
59+
60+
steps:
61+
- uses: actions/checkout@v4
62+
- uses: ./.github/actions/setup_rye
63+
- run: rye test -a
64+
65+
docs:
66+
name: Documentation build
67+
runs-on: [self-hosted, linux, x64]
68+
69+
steps:
70+
- uses: actions/checkout@v4
71+
- uses: ./.github/actions/setup_rye
72+
- name: Run documentation build
73+
run: rye run docs
74+
75+
all_good:
76+
# This job does nothing and is only used for the branch protection
77+
# see https://github.com/marketplace/actions/alls-green#why
78+
79+
if: ${{ !cancelled() }}
80+
81+
needs:
82+
- pre-commit
83+
- mypy
84+
- pytest
85+
- docs
86+
87+
runs-on: [self-hosted, linux, x64]
88+
89+
steps:
90+
- name: Decide whether the needed jobs succeeded or failed
91+
uses: re-actors/alls-green@release/v1
92+
with:
93+
jobs: ${{ toJSON(needs) }}

‎.github/workflows/gh_pages.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Workflow for building and deploying the Sphinx site to GitHub Pages
2+
#
3+
name: Deploy docs to GH Pages
4+
5+
on:
6+
# Runs on pushes targeting the default branch
7+
push:
8+
branches: ["main"]
9+
10+
# Allows you to run this workflow manually from the Actions tab
11+
workflow_dispatch:
12+
13+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
20+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
21+
concurrency:
22+
group: "pages"
23+
cancel-in-progress: false
24+
25+
jobs:
26+
build:
27+
name: Build
28+
runs-on: [self-hosted, linux, x64]
29+
steps:
30+
- uses: actions/checkout@v4
31+
- name: Setup Pages
32+
id: pages
33+
uses: actions/configure-pages@v5
34+
- uses: eifinger/setup-rye@v4
35+
- run: rye sync
36+
- name: Run documentation build
37+
run: rye run docs
38+
- name: Upload artifact
39+
uses: actions/upload-pages-artifact@v3
40+
with:
41+
path: docs/_build/html
42+
43+
deploy:
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
needs: build
48+
runs-on: [self-hosted, linux, x64]
49+
name: Deploy
50+
steps:
51+
- name: Deploy to GitHub Pages
52+
id: deployment
53+
uses: actions/deploy-pages@v4

‎.github/workflows/release.yaml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Release
2+
on:
3+
push:
4+
tags:
5+
- '[0-9].[0-9]+.[0-9]+'
6+
7+
permissions:
8+
id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
9+
contents: read
10+
11+
jobs:
12+
build:
13+
name: Build distribution 📦
14+
runs-on: ubuntu-latest
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
with:
19+
persist-credentials: false
20+
- name: Set up Python
21+
uses: actions/setup-python@v5
22+
with:
23+
python-version: "3.x"
24+
- name: Install pypa/build
25+
run: >-
26+
python3 -m
27+
pip install
28+
build
29+
--user
30+
- name: Build a binary wheel and a source tarball
31+
run: python3 -m build
32+
- name: Store the distribution packages
33+
uses: actions/upload-artifact@v4
34+
with:
35+
name: python-package-distributions
36+
path: dist/
37+
38+
publish-to-pypi:
39+
name: >-
40+
Publish Python 🐍 distribution 📦 to PyPI
41+
needs:
42+
- build
43+
runs-on: ubuntu-latest
44+
permissions:
45+
id-token: write # IMPORTANT: mandatory for trusted publishing
46+
steps:
47+
- name: Download all the dists
48+
uses: actions/download-artifact@v4
49+
with:
50+
name: python-package-distributions
51+
path: dist/
52+
- name: Publish distribution 📦 to PyPI
53+
uses: pypa/gh-action-pypi-publish@release/v1

‎.gitignore‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# python generated files
2+
.ruff_cache
3+
.pytest_cache
4+
.mypy_cache
5+
__pycache__/
6+
*.py[oc]
7+
build/
8+
dist/
9+
wheels/
10+
*.egg-info
11+
.venv
12+
13+
# lock files
14+
requirements.lock
15+
requirements-dev.lock
16+
17+
# Sphinx build output
18+
**/_build
19+
20+
# rye is the primary tool, uv is only used for on-the-fly setups
21+
uv.lock

‎.pre-commit-config.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
repos:
2+
- repo: https://github.com/pre-commit/pre-commit-hooks
3+
rev: v5.0.0
4+
hooks:
5+
- id: end-of-file-fixer
6+
- id: trailing-whitespace
7+
8+
- repo: https://github.com/astral-sh/ruff-pre-commit
9+
rev: v0.12.2
10+
hooks:
11+
- id: ruff-format
12+
name: python format
13+
- id: ruff
14+
alias: ruff-check
15+
name: python lint
16+
args: [--fix]
17+
18+
- repo: https://github.com/ComPWA/taplo-pre-commit
19+
rev: v0.9.3
20+
hooks:
21+
- id: taplo-format
22+
# lint fetches schemas online at each call, deactivate for now
23+
- id: taplo-lint

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.12.7

‎README.md‎

Lines changed: 37 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,37 @@
1-
* [ ] Move code
2-
* [ ] Create doc project, be based on ubCode/ubTrace
3-
* [ ] ubCode ubproject.toml
4-
* [ ] CI for docs and tests
5-
* [ ] DNS for codelinks.useblocks.com
6-
* [ ] Deployment on pypi (see Sphinx-Needs)
7-
* [ ] Repo rules (no main pushes / branch protection)
8-
* [ ] Cleanup ubTrace (files, ci, rye commands)
1+
# Sphinx CodeLinks
2+
3+
A Sphinx extension for discovering, linking, and documenting source code across projects.
4+
5+
## Features
6+
7+
- **Source Discovery**: Automatically discover source files in your project
8+
- **Virtual Documentation**: Generate documentation from code without modifying source files
9+
- **Code Linking**: Create intelligent links between code elements
10+
- **Sphinx Integration**: Seamless integration with existing Sphinx documentation
11+
12+
## Quick Start
13+
14+
```bash
15+
pip install sphinx-codelinks
16+
```
17+
18+
Add to your `conf.py`:
19+
20+
```python
21+
extensions = ['sphinx_needs', 'sphinx_codelinks']
22+
```
23+
24+
## Documentation
25+
26+
Full documentation: https://codelinks.useblocks.com
27+
28+
## Components
29+
30+
- **Source Discovery** ([`src/sphinx_codelinks/source_discovery`](src/sphinx_codelinks/source_discovery)): Code analysis and discovery
31+
- **Virtual Docs** ([`src/sphinx_codelinks/virtual_docs`](src/sphinx_codelinks/virtual_docs)): Documentation generation
32+
- **Sphinx Extension** ([`src/sphinx_codelinks/sphinx_extension`](src/sphinx_codelinks/sphinx_extension)): Sphinx integration
33+
- **Command Line** ([`src/sphinx_codelinks/cmd.py`](src/sphinx_codelinks/cmd.py)): CLI interface
34+
35+
## Development
36+
37+
See [Development Guide](docs/source/development/) for contributing guidelines.

‎docs/conf.py‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
from datetime import datetime
10+
from pathlib import Path
11+
import tomllib
12+
13+
_project_data = tomllib.loads(
14+
(Path(__file__).parent.parent / "pyproject.toml").read_text("utf8")
15+
)["project"]
16+
17+
project = _project_data["name"]
18+
author = _project_data["authors"][0]["name"]
19+
copyright = f"{datetime.now().year}, {author}"
20+
version = release = _project_data["version"]
21+
22+
# -- General configuration ---------------------------------------------------
23+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
24+
25+
extensions = [
26+
"sphinx_design",
27+
"sphinx_needs",
28+
"sphinx_codelinks",
29+
"sphinx.ext.intersphinx",
30+
"sphinx_code_tabs",
31+
"sphinxcontrib.typer",
32+
]
33+
34+
# exclude_patterns = []
35+
templates_path = ["_templates"]
36+
show_warning_types = True
37+
38+
todo_include_todos = True
39+
40+
# -- Options for intersphinx extension ---------------------------------------
41+
42+
intersphinx_mapping = {
43+
"needs": ("https://sphinx-needs.readthedocs.io/en/latest/", None),
44+
"sphinx": ("https://www.sphinx-doc.org/en/master", None),
45+
}
46+
47+
# -- Options for HTML output -------------------------------------------------
48+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
49+
50+
html_title = "CodeLinks"
51+
html_theme = "furo"
52+
# original source is in ubdocs repo at docs/developer_handbook/design/files/ubcode_favicon/favicon.ico
53+
html_favicon = "source/_static/favicon.ico"
54+
html_static_path = ["source/_static"]
55+
56+
html_theme_options = {
57+
"sidebar_hide_name": True,
58+
"top_of_page_buttons": ["view", "edit"],
59+
"source_repository": "https://github.com/useblocks/sphinx-codelinks",
60+
"source_branch": "main",
61+
"source_directory": "docs/source/",
62+
"light_logo": "sphinx-codelinks-logo_dark.svg",
63+
"dark_logo": "sphinx-codelinks-logo_light.svg",
64+
}
65+
html_css_files = ["furo.css"]
66+
67+
src_trace_config_from_toml = "./src_trace.toml"

‎docs/source/_static/favicon.ico‎

15 KB
Binary file not shown.

0 commit comments

Comments
 (0)