rhiza 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- rhiza-0.4.0.dist-info/METADATA +35 -0
- {rhiza-0.2.0.dist-info → rhiza-0.4.0.dist-info}/RECORD +5 -5
- rhiza-0.2.0.dist-info/METADATA +0 -690
- {rhiza-0.2.0.dist-info → rhiza-0.4.0.dist-info}/WHEEL +0 -0
- {rhiza-0.2.0.dist-info → rhiza-0.4.0.dist-info}/entry_points.txt +0 -0
- {rhiza-0.2.0.dist-info → rhiza-0.4.0.dist-info}/licenses/LICENSE +0 -0
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: rhiza
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Reusable configuration templates for modern Python projects
|
|
5
|
+
Project-URL: Homepage, https://github.com/jebel-quant/rhiza-cli
|
|
6
|
+
Project-URL: Repository, https://github.com/jebel-quant/rhiza-cli
|
|
7
|
+
Project-URL: Issues, https://github.com/jebel-quant/rhiza/issues-cli
|
|
8
|
+
Author: Thomas Schmelzer
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: ci,configuration,ruff,taskfile,templates
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Topic :: Software Development :: Build Tools
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Requires-Dist: loguru>=0.7.3
|
|
23
|
+
Requires-Dist: pyyaml==6.0.3
|
|
24
|
+
Requires-Dist: typer>=0.20.0
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: marimo==0.18.4; extra == 'dev'
|
|
27
|
+
Requires-Dist: pdoc>=16.0.0; extra == 'dev'
|
|
28
|
+
Requires-Dist: pre-commit==4.5.0; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest-html>=4.1.1; extra == 'dev'
|
|
31
|
+
Requires-Dist: pytest==9.0.2; extra == 'dev'
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
# rhiza-cli
|
|
35
|
+
Command line interface for Rhiza
|
|
@@ -4,8 +4,8 @@ rhiza/cli.py,sha256=FCCqwWZMDRSeDm6GERvlXkck0RSxq3rzWqUh3Q0XVJk,1343
|
|
|
4
4
|
rhiza/commands/__init__.py,sha256=X5ZRDDl37X8mEbiMWoqjTGlLhebkYhZ2SaLJd4KcHdw,166
|
|
5
5
|
rhiza/commands/hello.py,sha256=_zhLoGLM21cm5XBYohwm5gbsNMpJ96ZxCcLwHrwhKVs,216
|
|
6
6
|
rhiza/commands/inject.py,sha256=9MpS08TtOhjxIturzN2ejvEnrvGJUCGMjuS4JTuE2G4,5028
|
|
7
|
-
rhiza-0.
|
|
8
|
-
rhiza-0.
|
|
9
|
-
rhiza-0.
|
|
10
|
-
rhiza-0.
|
|
11
|
-
rhiza-0.
|
|
7
|
+
rhiza-0.4.0.dist-info/METADATA,sha256=as92HkPHqiwg4HWlwGkR7CCCRdw5s8cLASHnP2luFek,1388
|
|
8
|
+
rhiza-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
9
|
+
rhiza-0.4.0.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
|
|
10
|
+
rhiza-0.4.0.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
|
|
11
|
+
rhiza-0.4.0.dist-info/RECORD,,
|
rhiza-0.2.0.dist-info/METADATA
DELETED
|
@@ -1,690 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: rhiza
|
|
3
|
-
Version: 0.2.0
|
|
4
|
-
Summary: Reusable configuration templates for modern Python projects
|
|
5
|
-
Project-URL: Homepage, https://github.com/jebel-quant/rhiza
|
|
6
|
-
Project-URL: Repository, https://github.com/jebel-quant/rhiza
|
|
7
|
-
Project-URL: Issues, https://github.com/jebel-quant/rhiza/issues
|
|
8
|
-
Author: Thomas Schmelzer
|
|
9
|
-
License: MIT
|
|
10
|
-
License-File: LICENSE
|
|
11
|
-
Keywords: ci,configuration,ruff,taskfile,templates
|
|
12
|
-
Classifier: Intended Audience :: Developers
|
|
13
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
-
Classifier: Programming Language :: Python :: 3
|
|
15
|
-
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
-
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
-
Classifier: Topic :: Software Development :: Build Tools
|
|
21
|
-
Requires-Python: >=3.11
|
|
22
|
-
Requires-Dist: loguru>=0.7.3
|
|
23
|
-
Requires-Dist: pyyaml==6.0.3
|
|
24
|
-
Requires-Dist: typer>=0.20.0
|
|
25
|
-
Provides-Extra: dev
|
|
26
|
-
Requires-Dist: marimo==0.18.4; extra == 'dev'
|
|
27
|
-
Requires-Dist: pdoc>=16.0.0; extra == 'dev'
|
|
28
|
-
Requires-Dist: pre-commit==4.5.0; extra == 'dev'
|
|
29
|
-
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
|
|
30
|
-
Requires-Dist: pytest-html>=4.1.1; extra == 'dev'
|
|
31
|
-
Requires-Dist: pytest==9.0.2; extra == 'dev'
|
|
32
|
-
Description-Content-Type: text/markdown
|
|
33
|
-
|
|
34
|
-
<div align="center">
|
|
35
|
-
|
|
36
|
-
# <img src="assets/rhiza-logo.svg" alt="Rhiza Logo" width="30" style="vertical-align: middle;"> Rhiza
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
[](LICENSE)
|
|
40
|
-
[](https://www.python.org/)
|
|
41
|
-
[](https://github.com/astral-sh/ruff)
|
|
42
|
-
[](https://github.com/astral-sh/uv)
|
|
43
|
-
[](https://github.com/pypa/hatch)
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
[](https://github.com/jebel-quant/rhiza/actions)
|
|
47
|
-
[](https://github.com/jebel-quant/rhiza/actions?query=workflow%3APRE-COMMIT)
|
|
48
|
-
[](https://github.com/jebel-quant/rhiza/actions?query=workflow%3ADEPTRY)
|
|
49
|
-
[](https://github.com/jebel-quant/rhiza/actions?query=workflow%3ABOOK)
|
|
50
|
-
[](https://github.com/Jebel-Quant/rhiza/actions/workflows/marimo.yml)
|
|
51
|
-
|
|
52
|
-
[](https://codespaces.new/jebel-quant/rhiza)
|
|
53
|
-
|
|
54
|
-
A collection of reusable configuration templates
|
|
55
|
-
for modern Python projects.
|
|
56
|
-
Save time and maintain consistency across your projects
|
|
57
|
-
with these pre-configured templates.
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
</div>
|
|
62
|
-
|
|
63
|
-
## ✨ Features
|
|
64
|
-
|
|
65
|
-
- 🚀 **CI/CD Templates** - Ready-to-use GitHub Actions and GitLab CI workflows
|
|
66
|
-
- 🧪 **Testing Framework** - Comprehensive test setup with pytest
|
|
67
|
-
- 📚 **Documentation** - Automated documentation generation
|
|
68
|
-
- 🔍 **Code Quality** - Linting, formatting, and dependency checking
|
|
69
|
-
- 📝 **Editor Configuration** - Cross-platform .editorconfig for consistent coding style
|
|
70
|
-
- 📊 **Marimo Integration** - Interactive notebook support
|
|
71
|
-
|
|
72
|
-
## 🚀 Getting Started
|
|
73
|
-
|
|
74
|
-
Start by cloning the repository:
|
|
75
|
-
|
|
76
|
-
```bash
|
|
77
|
-
# Clone the repository
|
|
78
|
-
git clone https://github.com/jebel-quant/rhiza.git
|
|
79
|
-
cd rhiza
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
The project uses a [Makefile](Makefile) as the primary entry point for all tasks.
|
|
83
|
-
It relies on [uv and uvx](https://github.com/astral-sh/uv) for fast Python package management.
|
|
84
|
-
|
|
85
|
-
Install all dependencies using:
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
make install
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
This will:
|
|
92
|
-
- Install `uv` and `uvx` into the `bin/` directory
|
|
93
|
-
- Create a Python virtual environment in `.venv/`
|
|
94
|
-
- Install all project dependencies from `pyproject.toml`
|
|
95
|
-
|
|
96
|
-
Both the `.venv` and `bin` directories are listed in `.gitignore`.
|
|
97
|
-
|
|
98
|
-
## 📋 Available Tasks
|
|
99
|
-
|
|
100
|
-
Run `make help` to see all available targets:
|
|
101
|
-
|
|
102
|
-
```makefile
|
|
103
|
-
Usage:
|
|
104
|
-
make <target>
|
|
105
|
-
|
|
106
|
-
Targets:
|
|
107
|
-
|
|
108
|
-
Bootstrap
|
|
109
|
-
install-uv ensure uv/uvx is installed
|
|
110
|
-
install-extras run custom build script (if exists)
|
|
111
|
-
install install
|
|
112
|
-
clean clean
|
|
113
|
-
|
|
114
|
-
Development and Testing
|
|
115
|
-
test run all tests
|
|
116
|
-
marimo fire up Marimo server
|
|
117
|
-
marimushka export Marimo notebooks to HTML
|
|
118
|
-
deptry run deptry if pyproject.toml exists
|
|
119
|
-
|
|
120
|
-
Documentation
|
|
121
|
-
docs create documentation with pdoc
|
|
122
|
-
book compile the companion book
|
|
123
|
-
fmt check the pre-commit hooks and the linting
|
|
124
|
-
all Run everything
|
|
125
|
-
|
|
126
|
-
Releasing and Versioning
|
|
127
|
-
bump bump version
|
|
128
|
-
release create tag and push to remote with prompts
|
|
129
|
-
post-release perform post-release tasks
|
|
130
|
-
|
|
131
|
-
Meta
|
|
132
|
-
sync sync with template repository as defined in .github/template.yml
|
|
133
|
-
help Display this help message
|
|
134
|
-
customisations list available customisation scripts
|
|
135
|
-
update-readme update README.md with current Makefile help output
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
The [Makefile](Makefile) provides organized targets for bootstrapping, development, testing, and documentation tasks.
|
|
139
|
-
|
|
140
|
-
> **Note:** The help output above is automatically generated from the Makefile.
|
|
141
|
-
> When you modify Makefile targets or descriptions, run `make update-readme` to update this section,
|
|
142
|
-
> or the pre-commit hook will update it automatically when you commit changes to the Makefile.
|
|
143
|
-
|
|
144
|
-
## 📊 Marimo Notebooks
|
|
145
|
-
|
|
146
|
-
This project supports [Marimo](https://marimo.io/) notebooks. You can run the Marimo server using:
|
|
147
|
-
|
|
148
|
-
```bash
|
|
149
|
-
make marimo
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
### Configuration
|
|
153
|
-
|
|
154
|
-
To ensure Marimo can import the local package (`src/config`), the following configuration is added to `pyproject.toml`:
|
|
155
|
-
|
|
156
|
-
```toml
|
|
157
|
-
[tool.marimo.runtime]
|
|
158
|
-
pythonpath = ["src"]
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
### Dependency Management
|
|
162
|
-
|
|
163
|
-
Marimo notebooks can define their own dependencies using inline script metadata. This allows notebooks to be self-contained and reproducible.
|
|
164
|
-
|
|
165
|
-
To use the current package (`rhiza`) within a notebook, you can define it as a dependency and point `uv` to the local path. Add the following block at the top of your `.py` notebook file:
|
|
166
|
-
|
|
167
|
-
```python
|
|
168
|
-
# /// script
|
|
169
|
-
# requires-python = ">=3.11"
|
|
170
|
-
# dependencies = [
|
|
171
|
-
# "marimo",
|
|
172
|
-
# "pandas",
|
|
173
|
-
# "rhiza",
|
|
174
|
-
# ]
|
|
175
|
-
#
|
|
176
|
-
# [tool.uv.sources]
|
|
177
|
-
# rhiza = { path = "../.." }
|
|
178
|
-
# ///
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
Adjust the `path` in `[tool.uv.sources]` relative to the notebook's location.
|
|
182
|
-
|
|
183
|
-
## Testing your documentation
|
|
184
|
-
|
|
185
|
-
Any README.md file will be scanned for Python code blocks.
|
|
186
|
-
If any are found, they will be tested in [test_readme.py](tests/test_config_templates/test_readme.py).
|
|
187
|
-
|
|
188
|
-
```python
|
|
189
|
-
# Some generic Python code block
|
|
190
|
-
import math
|
|
191
|
-
print("Hello, World!")
|
|
192
|
-
print(1 + 1)
|
|
193
|
-
print(round(math.pi, 2))
|
|
194
|
-
print(round(math.cos(math.pi/4.0), 2))
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
For each code block, we define a block of expected output.
|
|
198
|
-
If the output matches the expected output, a [test](tests/test_config_templates/test_readme.py) passes,
|
|
199
|
-
Otherwise, it fails.
|
|
200
|
-
|
|
201
|
-
```result
|
|
202
|
-
Hello, World!
|
|
203
|
-
2
|
|
204
|
-
3.14
|
|
205
|
-
0.71
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
## 📁 Available Templates
|
|
209
|
-
|
|
210
|
-
This repository provides a curated set of reusable configuration templates, organised by purpose.
|
|
211
|
-
|
|
212
|
-
### 🌱 Core Project Configuration
|
|
213
|
-
Foundational files that define project structure, standards, and contribution practices.
|
|
214
|
-
|
|
215
|
-
- **.gitignore** — Sensible defaults for Python projects
|
|
216
|
-
- **.editorconfig** — Editor configuration to enforce consistent coding standards
|
|
217
|
-
- **ruff.toml** — Configuration for the Ruff linter and formatter
|
|
218
|
-
- **pytest.ini** — Configuration for the `pytest` testing framework
|
|
219
|
-
- **Makefile** — Simple make targets for common development tasks
|
|
220
|
-
- **CODE_OF_CONDUCT.md** — Generic code of conduct for open-source projects
|
|
221
|
-
- **CONTRIBUTING.md** — Generic contributing guidelines for open-source projects
|
|
222
|
-
|
|
223
|
-
### 🔧 Developer Experience
|
|
224
|
-
Tooling that improves local development, onboarding, and reproducibility.
|
|
225
|
-
|
|
226
|
-
- **.devcontainer/** — Development container setup (VS Code / Dev Containers)
|
|
227
|
-
- **.pre-commit-config.yaml** — Common and useful pre-commit hooks
|
|
228
|
-
- **docker/** — Example `Dockerfile` and `.dockerignore`
|
|
229
|
-
|
|
230
|
-
### 🚀 CI / CD & Automation
|
|
231
|
-
Templates related to continuous integration, delivery, and repository automation.
|
|
232
|
-
|
|
233
|
-
- **.github/** — GitHub Actions workflows, scripts, and repository templates
|
|
234
|
-
|
|
235
|
-
## ⚙️ Workflow Configuration
|
|
236
|
-
|
|
237
|
-
The GitHub Actions workflows can be customized using repository variables:
|
|
238
|
-
|
|
239
|
-
### Python Version Control
|
|
240
|
-
|
|
241
|
-
Control which Python versions are used in your workflows:
|
|
242
|
-
|
|
243
|
-
- **`PYTHON_MAX_VERSION`** - Maximum Python version for CI testing matrix
|
|
244
|
-
- Default: `'3.14'` (tests on 3.11, 3.12, 3.13, 3.14)
|
|
245
|
-
- Set to `'3.13'` to test on 3.11, 3.12, 3.13 only
|
|
246
|
-
- Set to `'3.12'` to test on 3.11, 3.12 only
|
|
247
|
-
- Set to `'3.11'` to test on 3.11 only
|
|
248
|
-
|
|
249
|
-
- **`PYTHON_DEFAULT_VERSION`** - Default Python version for release, pre-commit, book, and marimo workflows
|
|
250
|
-
- Default: `'3.14'`
|
|
251
|
-
- Set to `'3.12'` or `'3.13'` if dependencies are not compatible with newer versions
|
|
252
|
-
|
|
253
|
-
**To set these variables:**
|
|
254
|
-
|
|
255
|
-
1. Go to your repository Settings → Secrets and variables → Actions → Variables tab
|
|
256
|
-
2. Click "New repository variable"
|
|
257
|
-
3. Add `PYTHON_MAX_VERSION` and/or `PYTHON_DEFAULT_VERSION` with your desired values
|
|
258
|
-
|
|
259
|
-
## 🧩 Bringing Rhiza into an Existing Project
|
|
260
|
-
|
|
261
|
-
Rhiza provides reusable configuration templates that you can integrate into your existing Python projects.
|
|
262
|
-
You can choose to adopt all templates or selectively pick the ones that fit your needs.
|
|
263
|
-
|
|
264
|
-
### Prerequisites
|
|
265
|
-
|
|
266
|
-
Before integrating Rhiza into your existing project:
|
|
267
|
-
|
|
268
|
-
- **Python 3.11+** - Ensure your project supports Python 3.11 or newer
|
|
269
|
-
- **Git** - Your project should be a Git repository
|
|
270
|
-
- **Backup** - Consider committing any uncommitted changes before integration
|
|
271
|
-
- **Review** - Review the [Available Templates](#-available-templates) section to understand what could be added
|
|
272
|
-
|
|
273
|
-
### Quick Start: Automated Injection
|
|
274
|
-
|
|
275
|
-
The fastest way to integrate Rhiza is using the provided `inject_rhiza.sh` script:
|
|
276
|
-
|
|
277
|
-
```bash
|
|
278
|
-
# Navigate to your repository
|
|
279
|
-
cd /path/to/your/project
|
|
280
|
-
|
|
281
|
-
# Run the injection script
|
|
282
|
-
uvx rhiza .
|
|
283
|
-
```
|
|
284
|
-
|
|
285
|
-
This will:
|
|
286
|
-
- ✅ Create a default template configuration (`.github/template.yml`)
|
|
287
|
-
- ✅ Perform an initial sync of a basic set of templates
|
|
288
|
-
- ✅ Provide clear next steps for review and customization
|
|
289
|
-
|
|
290
|
-
**Options:**
|
|
291
|
-
- `--branch <branch>` - Use a specific rhiza branch (default: main)
|
|
292
|
-
- `--help` - Show detailed usage information
|
|
293
|
-
|
|
294
|
-
**Example with branch option:**
|
|
295
|
-
```bash
|
|
296
|
-
# Use a development branch
|
|
297
|
-
uvx --branch develop .
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
### Method 1: Manual Integration (Selective Adoption)
|
|
301
|
-
|
|
302
|
-
This approach is ideal if you want to cherry-pick specific templates or customize them before integration.
|
|
303
|
-
|
|
304
|
-
#### Step 1: Clone Rhiza
|
|
305
|
-
|
|
306
|
-
First, clone the Rhiza repository to a temporary location:
|
|
307
|
-
|
|
308
|
-
```bash
|
|
309
|
-
# Clone to a temporary directory
|
|
310
|
-
cd /tmp
|
|
311
|
-
git clone https://github.com/jebel-quant/rhiza.git
|
|
312
|
-
```
|
|
313
|
-
|
|
314
|
-
#### Step 2: Copy Desired Templates
|
|
315
|
-
|
|
316
|
-
Navigate to your project and copy the configuration files you need:
|
|
317
|
-
|
|
318
|
-
```bash
|
|
319
|
-
# Navigate to your project
|
|
320
|
-
cd /path/to/your/project
|
|
321
|
-
|
|
322
|
-
# We recommend working on a fresh branch
|
|
323
|
-
git checkout -b rhiza
|
|
324
|
-
|
|
325
|
-
# Ensure required directories exist
|
|
326
|
-
mkdir -p .github/workflows
|
|
327
|
-
mkdir -p .github/scripts
|
|
328
|
-
|
|
329
|
-
# Copy the template configuration
|
|
330
|
-
cp /tmp/rhiza/.github/template.yml .github/template.yml
|
|
331
|
-
|
|
332
|
-
# Copy the sync helper script
|
|
333
|
-
cp /tmp/rhiza/.github/scripts/sync.sh .github/scripts
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
At this stage:
|
|
337
|
-
|
|
338
|
-
- ❌ No templates are copied yet
|
|
339
|
-
- ❌ No existing files are modified
|
|
340
|
-
- ✅ Only the sync mechanism is installed
|
|
341
|
-
- ⚠️ **Do not merge this branch yet.**
|
|
342
|
-
|
|
343
|
-
#### Step 3: Perform the first sync
|
|
344
|
-
|
|
345
|
-
Run the sync script to apply the templates defined in '.github/template.yml'
|
|
346
|
-
|
|
347
|
-
```bash
|
|
348
|
-
./.github/scripts/sync.sh
|
|
349
|
-
```
|
|
350
|
-
|
|
351
|
-
This will:
|
|
352
|
-
|
|
353
|
-
- Fetch the selected templates from the Rhiza repository
|
|
354
|
-
- Apply them locally according to your include/exclude rules
|
|
355
|
-
- Stage or commit the resulting changes on the current branch
|
|
356
|
-
|
|
357
|
-
Review the changes carefully:
|
|
358
|
-
|
|
359
|
-
```bash
|
|
360
|
-
git status
|
|
361
|
-
git diff
|
|
362
|
-
```
|
|
363
|
-
|
|
364
|
-
If happy with the suggested changes push them
|
|
365
|
-
|
|
366
|
-
```bash
|
|
367
|
-
git add .
|
|
368
|
-
git commit -m "Integrate Rhiza templates"
|
|
369
|
-
git push -u origin rhiza
|
|
370
|
-
```
|
|
371
|
-
|
|
372
|
-
### Method 2: Automated Sync (Continuous Updates)
|
|
373
|
-
|
|
374
|
-
This approach keeps your project’s configuration in sync with Rhiza’s latest templates while giving you control over which files are applied.
|
|
375
|
-
|
|
376
|
-
Prerequisites:
|
|
377
|
-
|
|
378
|
-
- A .github/template.yml file exists, defining **which templates to include or exclude**.
|
|
379
|
-
- The first manual sync (./.github/scripts/sync.sh) has been performed.
|
|
380
|
-
- The .github/workflows/sync.yml workflow is present in your repository.
|
|
381
|
-
|
|
382
|
-
The workflow can run:
|
|
383
|
-
|
|
384
|
-
**On a schedule** — e.g., weekly updates
|
|
385
|
-
**Manually** — via the GitHub Actions “Run workflow” button
|
|
386
|
-
|
|
387
|
-
⚠️ .github/template.yml remains the **source of truth**. All automated updates are driven by its include/exclude rules.
|
|
388
|
-
|
|
389
|
-
#### Step 1: Configure GitHub Token
|
|
390
|
-
|
|
391
|
-
If you want the sync workflow to trigger other workflows (e.g. to create pull requests), create a Personal Access Token (PAT):
|
|
392
|
-
|
|
393
|
-
1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
|
|
394
|
-
2. Generate a new token with `repo` and `workflow` scopes
|
|
395
|
-
3. Add it as a repository secret named `PAT_TOKEN`
|
|
396
|
-
4. Update the workflow to use `token: ${{ secrets.PAT_TOKEN }}`
|
|
397
|
-
|
|
398
|
-
#### Step 2: Run Initial Sync (again)
|
|
399
|
-
|
|
400
|
-
You can trigger the sync workflow manually:
|
|
401
|
-
|
|
402
|
-
1. Go to your repository's "Actions" tab
|
|
403
|
-
2. Select the "Sync Templates" workflow
|
|
404
|
-
3. Click "Run workflow"
|
|
405
|
-
4. Review and merge the resulting pull request
|
|
406
|
-
|
|
407
|
-
The workflow will:
|
|
408
|
-
- Download the latest templates from Rhiza
|
|
409
|
-
- Copy them to your project based on your `template.yml` configuration
|
|
410
|
-
- Create a pull request with the changes (if any)
|
|
411
|
-
- Automatically run weekly to keep your templates up to date
|
|
412
|
-
|
|
413
|
-
### What to Expect After Integration
|
|
414
|
-
|
|
415
|
-
After integrating Rhiza, your project will have:
|
|
416
|
-
|
|
417
|
-
- **Automated CI/CD** - GitHub Actions workflows for testing, linting, and releases
|
|
418
|
-
- **Code Quality Tools** - Pre-commit hooks, ruff formatting, and pytest configuration
|
|
419
|
-
- **Task Automation** - Makefile with common development tasks (`make test`, `make fmt`, etc.)
|
|
420
|
-
- **Dev Container** - Optional VS Code/Codespaces development environment
|
|
421
|
-
- **Documentation** - Templates for automated documentation generation
|
|
422
|
-
|
|
423
|
-
### Next Steps
|
|
424
|
-
|
|
425
|
-
1. **Test the integration** - Run `make test` to ensure tests pass
|
|
426
|
-
2. **Run pre-commit** - Execute `make fmt` to verify code quality checks
|
|
427
|
-
3. **Review workflows** - Check GitHub Actions tabs to see workflows in action
|
|
428
|
-
4. **Customize** - Adjust templates to match your project's specific needs
|
|
429
|
-
5. **Update documentation** - Add project-specific instructions to your README
|
|
430
|
-
|
|
431
|
-
### Troubleshooting
|
|
432
|
-
|
|
433
|
-
**Issue: Makefile targets conflict with existing scripts**
|
|
434
|
-
- Solution: Review the Makefile and merge targets with your existing build scripts, or rename conflicting targets
|
|
435
|
-
|
|
436
|
-
**Issue: Pre-commit hooks fail on existing code**
|
|
437
|
-
- Solution: Run `make fmt` to fix formatting issues, or temporarily exclude certain files in `.pre-commit-config.yaml`
|
|
438
|
-
|
|
439
|
-
**Issue: GitHub Actions workflows fail**
|
|
440
|
-
- Solution: Check Python version compatibility and adjust `PYTHON_MAX_VERSION` repository variable if needed
|
|
441
|
-
|
|
442
|
-
**Issue: Dev container fails to build**
|
|
443
|
-
- Solution: Review `.devcontainer/devcontainer.json` and ensure all dependencies are available for your project
|
|
444
|
-
|
|
445
|
-
## 🖥️ Dev Container Compatibility
|
|
446
|
-
|
|
447
|
-
This repository includes a
|
|
448
|
-
template **Dev Container** configuration
|
|
449
|
-
for seamless development experience in
|
|
450
|
-
both **VS Code** and **GitHub Codespaces**.
|
|
451
|
-
|
|
452
|
-
### What's Configured
|
|
453
|
-
|
|
454
|
-
The `.devcontainer` setup provides:
|
|
455
|
-
|
|
456
|
-
- 🐍 **Python 3.14** runtime environment
|
|
457
|
-
- 🔧 **UV Package Manager** - Fast Python package installer and resolver
|
|
458
|
-
- ⚡ **Makefile** - For running project workflows
|
|
459
|
-
- 🧪 **Pre-commit Hooks** - Automated code quality checks
|
|
460
|
-
- 📊 **Marimo Integration** - Interactive notebook support with VS Code extension
|
|
461
|
-
- 🔍 **Python Development Tools** - Pylance, Python extension, and optimized settings
|
|
462
|
-
- 🚀 **Port Forwarding** - Port 8080 for development servers
|
|
463
|
-
- 🔐 **SSH Agent Forwarding** - Full Git functionality with your host SSH keys
|
|
464
|
-
|
|
465
|
-
### Usage
|
|
466
|
-
|
|
467
|
-
#### In VS Code
|
|
468
|
-
|
|
469
|
-
1. Install the "Dev Containers" extension
|
|
470
|
-
2. Open the repository in VS Code
|
|
471
|
-
3. Click "Reopen in Container" when prompted
|
|
472
|
-
4. The environment will automatically set up with all dependencies
|
|
473
|
-
|
|
474
|
-
#### In GitHub Codespaces
|
|
475
|
-
|
|
476
|
-
1. Navigate to the repository on GitHub
|
|
477
|
-
2. Click the green "Code" button
|
|
478
|
-
3. Select "Codespaces" tab
|
|
479
|
-
4. Click "Create codespace on main" (or your branch)
|
|
480
|
-
5. Your development environment will be ready in minutes
|
|
481
|
-
|
|
482
|
-
The dev container automatically runs the initialization script that:
|
|
483
|
-
|
|
484
|
-
- Installs UV package manager
|
|
485
|
-
- Configures the Python virtual environment
|
|
486
|
-
- Installs project dependencies
|
|
487
|
-
- Sets up pre-commit hooks
|
|
488
|
-
|
|
489
|
-
### Publishing Devcontainer Images
|
|
490
|
-
|
|
491
|
-
The repository includes workflows for building and publishing devcontainer images:
|
|
492
|
-
|
|
493
|
-
#### CI Validation
|
|
494
|
-
|
|
495
|
-
The **DEVCONTAINER** workflow automatically validates that your devcontainer builds successfully:
|
|
496
|
-
- Triggers on changes to `.devcontainer/**` files or the workflow itself
|
|
497
|
-
- Builds the image without publishing (`push: never`)
|
|
498
|
-
- Works on pushes to any branch and pull requests
|
|
499
|
-
- Gracefully skips if no `.devcontainer/devcontainer.json` exists
|
|
500
|
-
|
|
501
|
-
### VS Code Dev Container SSH Agent Forwarding
|
|
502
|
-
|
|
503
|
-
Dev containers launched locally via VS code
|
|
504
|
-
are configured with SSH agent forwarding
|
|
505
|
-
to enable seamless Git operations:
|
|
506
|
-
|
|
507
|
-
- **Mounts your SSH directory** - Your `~/.ssh` folder is mounted into the container
|
|
508
|
-
- **Forwards SSH agent** - Your host's SSH agent is available inside the container
|
|
509
|
-
- **Enables Git operations** - Push, pull, and clone using your existing SSH keys
|
|
510
|
-
- **Works transparently** - No additional setup required in VS Code dev containers
|
|
511
|
-
|
|
512
|
-
### Troubleshooting
|
|
513
|
-
|
|
514
|
-
Common issues and solutions when using this configuration template.
|
|
515
|
-
|
|
516
|
-
---
|
|
517
|
-
|
|
518
|
-
#### SSH authentication fails on macOS when using devcontainer
|
|
519
|
-
|
|
520
|
-
**Symptom**: When building or using the devcontainer on macOS, Git operations (pull, push, clone) fail with SSH authentication errors, even though your SSH keys work fine on the host.
|
|
521
|
-
|
|
522
|
-
**Cause**: macOS SSH config often includes `UseKeychain yes`, which is a macOS-specific directive. When the devcontainer mounts your `~/.ssh` directory, other platforms (Linux containers) don't recognize this directive and fail to parse the SSH config.
|
|
523
|
-
|
|
524
|
-
**Solution**: Add `IgnoreUnknown UseKeychain` to the top of your `~/.ssh/config` file on your Mac:
|
|
525
|
-
|
|
526
|
-
```ssh-config
|
|
527
|
-
# At the top of ~/.ssh/config
|
|
528
|
-
IgnoreUnknown UseKeychain
|
|
529
|
-
|
|
530
|
-
Host *
|
|
531
|
-
AddKeysToAgent yes
|
|
532
|
-
UseKeychain yes
|
|
533
|
-
IdentityFile ~/.ssh/id_rsa
|
|
534
|
-
```
|
|
535
|
-
|
|
536
|
-
This tells SSH clients on non-macOS platforms to ignore the `UseKeychain` directive instead of failing.
|
|
537
|
-
|
|
538
|
-
**Reference**: [Stack Overflow solution](https://stackoverflow.com/questions/75613632/trying-to-ssh-to-my-server-from-the-terminal-ends-with-error-line-x-bad-configu/75616369#75616369)
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
## 🔧 Custom Build Extras
|
|
542
|
-
|
|
543
|
-
The project includes a hook for installing additional system dependencies and custom build steps needed across all build phases.
|
|
544
|
-
|
|
545
|
-
### Using build-extras.sh
|
|
546
|
-
|
|
547
|
-
Create a file `.github/scripts/customisations/build-extras.sh` in your repository to install system packages or dependencies (this repository uses a dedicated `customisations` folder for repo-specific scripts):
|
|
548
|
-
```bash
|
|
549
|
-
#!/bin/bash
|
|
550
|
-
set -euo pipefail
|
|
551
|
-
|
|
552
|
-
# Example: Install graphviz for diagram generation
|
|
553
|
-
sudo apt-get update
|
|
554
|
-
sudo apt-get install -y graphviz
|
|
555
|
-
|
|
556
|
-
# Add other custom installation commands here
|
|
557
|
-
```
|
|
558
|
-
|
|
559
|
-
### When it Runs
|
|
560
|
-
|
|
561
|
-
The `build-extras.sh` script (from `.github/scripts/customisations`) is automatically invoked during:
|
|
562
|
-
- `make install` - Initial project setup
|
|
563
|
-
- `make test` - Before running tests
|
|
564
|
-
- `make book` - Before building documentation
|
|
565
|
-
- `make docs` - Before generating API documentation
|
|
566
|
-
|
|
567
|
-
This ensures custom dependencies are available whenever needed throughout the build lifecycle. The `Makefile` intentionally only checks the `.github/scripts/customisations` folder for repository-specific hooks such as `build-extras.sh` and `post-release.sh`.
|
|
568
|
-
|
|
569
|
-
### Important: Exclude from Template Updates
|
|
570
|
-
|
|
571
|
-
If you customize this file, add it to the exclude list in your `action.yml` configuration to prevent it from being overwritten during template updates. Use the `customisations` path to avoid clobbering:
|
|
572
|
-
```yaml
|
|
573
|
-
exclude: |
|
|
574
|
-
.github/scripts/customisations/build-extras.sh
|
|
575
|
-
```
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
### Common Use Cases
|
|
579
|
-
|
|
580
|
-
- Installing graphviz for diagram rendering
|
|
581
|
-
- Adding LaTeX for mathematical notation
|
|
582
|
-
- Installing system libraries for specialized tools
|
|
583
|
-
- Setting up additional build dependencies
|
|
584
|
-
- Downloading external resources or tools
|
|
585
|
-
|
|
586
|
-
### Post-release scripts
|
|
587
|
-
|
|
588
|
-
If you need repository-specific post-release tasks, place a `post-release.sh` script in `.github/scripts/customisations/post-release.sh`. The `Makefile` will only look in the `customisations` folder for that hook.
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
## 🚀 Releasing
|
|
592
|
-
|
|
593
|
-
This template includes a robust release workflow that handles version bumping, tagging, and publishing.
|
|
594
|
-
|
|
595
|
-
### The Release Process
|
|
596
|
-
|
|
597
|
-
The release process consists of two interactive steps: **Bump** and **Release**.
|
|
598
|
-
|
|
599
|
-
#### 1. Bump Version
|
|
600
|
-
|
|
601
|
-
First, update the version in `pyproject.toml`:
|
|
602
|
-
|
|
603
|
-
```bash
|
|
604
|
-
make bump
|
|
605
|
-
```
|
|
606
|
-
|
|
607
|
-
This command will interactively guide you through:
|
|
608
|
-
1. Selecting a bump type (patch, minor, major) or entering a specific version
|
|
609
|
-
2. Warning you if you're not on the default branch
|
|
610
|
-
3. Showing the current and new version
|
|
611
|
-
4. Prompting whether to commit the changes
|
|
612
|
-
5. Prompting whether to push the changes
|
|
613
|
-
|
|
614
|
-
The script ensures safety by:
|
|
615
|
-
- Checking for uncommitted changes before bumping
|
|
616
|
-
- Validating that the tag doesn't already exist
|
|
617
|
-
- Verifying the version format
|
|
618
|
-
|
|
619
|
-
#### 2. Release
|
|
620
|
-
|
|
621
|
-
Once the version is bumped and committed, run the release command:
|
|
622
|
-
|
|
623
|
-
```bash
|
|
624
|
-
make release
|
|
625
|
-
```
|
|
626
|
-
|
|
627
|
-
This command will interactively guide you through:
|
|
628
|
-
1. Checking if your branch is up-to-date with the remote
|
|
629
|
-
2. If your local branch is ahead, showing the unpushed commits and prompting you to push them
|
|
630
|
-
3. Creating a git tag (e.g., `v1.2.4`)
|
|
631
|
-
4. Pushing the tag to the remote, which triggers the GitHub Actions release workflow
|
|
632
|
-
|
|
633
|
-
The script provides safety checks by:
|
|
634
|
-
- Warning if you're not on the default branch
|
|
635
|
-
- Verifying no uncommitted changes exist
|
|
636
|
-
- Checking if the tag already exists locally or on remote
|
|
637
|
-
- Showing the number of commits since the last tag
|
|
638
|
-
|
|
639
|
-
### What Happens After Release
|
|
640
|
-
|
|
641
|
-
The release workflow (`.github/workflows/release.yml`) triggers on the tag push and:
|
|
642
|
-
|
|
643
|
-
1. **Validates** - Checks the tag format and ensures no duplicate releases
|
|
644
|
-
2. **Builds** - Builds the Python package (if `pyproject.toml` exists)
|
|
645
|
-
3. **Drafts** - Creates a draft GitHub release with artifacts
|
|
646
|
-
4. **PyPI** - Publishes to PyPI (if not marked private)
|
|
647
|
-
5. **Devcontainer** - Publishes devcontainer image (if `PUBLISH_DEVCONTAINER=true`)
|
|
648
|
-
6. **Finalizes** - Publishes the GitHub release with links to PyPI and container images
|
|
649
|
-
|
|
650
|
-
### Configuration Options
|
|
651
|
-
|
|
652
|
-
**Python Version Configuration:**
|
|
653
|
-
- Set repository variable `PYTHON_MAX_VERSION` to control maximum Python version in CI tests
|
|
654
|
-
- Options: `'3.11'`, `'3.12'`, `'3.13'`, or `'3.14'` (default)
|
|
655
|
-
- Example: Set to `'3.13'` to test on Python 3.11, 3.12, and 3.13 only
|
|
656
|
-
- Set repository variable `PYTHON_DEFAULT_VERSION` to control default Python version in workflows
|
|
657
|
-
- Options: `'3.11'`, `'3.12'`, `'3.13'`, or `'3.14'` (default)
|
|
658
|
-
- Example: Set to `'3.12'` if dependencies are not compatible with Python 3.14
|
|
659
|
-
- Used in release, pre-commit, book, and marimo workflows
|
|
660
|
-
|
|
661
|
-
**PyPI Publishing:**
|
|
662
|
-
- Automatic if package is registered as a Trusted Publisher
|
|
663
|
-
- Use `PYPI_REPOSITORY_URL` and `PYPI_TOKEN` for custom feeds
|
|
664
|
-
- Mark as private with `Private :: Do Not Upload` in `pyproject.toml`
|
|
665
|
-
|
|
666
|
-
**Devcontainer Publishing:**
|
|
667
|
-
- Set repository variable `PUBLISH_DEVCONTAINER=true` to enable
|
|
668
|
-
- Override registry with `DEVCONTAINER_REGISTRY` variable (defaults to ghcr.io)
|
|
669
|
-
- Requires `.devcontainer/devcontainer.json` to exist
|
|
670
|
-
- Image published as `{registry}/{owner}/{repository}/devcontainer:vX.Y.Z`
|
|
671
|
-
|
|
672
|
-
## 🤝 Contributing
|
|
673
|
-
|
|
674
|
-
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
675
|
-
|
|
676
|
-
1. Fork the repository
|
|
677
|
-
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
|
678
|
-
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
679
|
-
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
680
|
-
5. Open a Pull Request
|
|
681
|
-
|
|
682
|
-
## 📄 License
|
|
683
|
-
|
|
684
|
-
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
685
|
-
|
|
686
|
-
## 🙏 Acknowledgments
|
|
687
|
-
|
|
688
|
-
- [GitHub Actions](https://github.com/features/actions) - For CI/CD capabilities
|
|
689
|
-
- [Marimo](https://marimo.io/) - For interactive notebooks
|
|
690
|
-
- [UV](https://github.com/astral-sh/uv) - For fast Python package operations
|
|
File without changes
|
|
File without changes
|
|
File without changes
|