mirror of
https://gitlab.com/Anson-Projects/projects.git
synced 2025-09-14 09:35:04 +00:00
47 lines
2.5 KiB
Markdown
47 lines
2.5 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- `ghost-upload/`: Rust automation for Ghost CMS publishing.
|
|
- `posts/`: Quarto posts with Julia/Python code per post directory.
|
|
- `public/`: Quarto build output (generated by `quarto render`).
|
|
- Root: Quarto config (`_quarto.yml`), shared assets, CI/CD, docs.
|
|
|
|
## Build, Test, and Development Commands
|
|
- Rust (`ghost-upload/`):
|
|
- Build: `cd ghost-upload && cargo build`
|
|
- Run: `cd ghost-upload && cargo run`
|
|
- Test: `cd ghost-upload && cargo test` (single: `cargo test <test_name>`)
|
|
- Lint: `cd ghost-upload && cargo clippy`
|
|
- Format: `cd ghost-upload && cargo fmt`
|
|
- Julia (root or `posts/*/`):
|
|
- Packages: `julia -e "using Pkg; Pkg.instantiate()"`
|
|
- Precompile: `julia -e "using Pkg; Pkg.precompile()"`
|
|
- Run notebook/script: `julia <filename>.jl`
|
|
- Quarto (docs/site):
|
|
- Build site: `quarto render --to html --output-dir public`
|
|
- Preview: `quarto preview`
|
|
- Check: `quarto check`
|
|
- Docker: `docker build -t projects .` then `docker run projects`
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Rust: `cargo fmt`; fix all `cargo clippy` warnings. Use `?` over `unwrap()`. Imports: std → external → local. Naming: snake_case (fn/vars), PascalCase (types). Public docs with `///`.
|
|
- Julia: 4-space indent; spaces around operators; group `using` at top; snake_case; prefer pipelines `|>` for DataFrames; handle expected errors with try-catch.
|
|
- Quarto: Include title/date in YAML; set `echo: false`, `warning: false` for clean outputs; descriptive figure captions and alt text.
|
|
|
|
## Testing Guidelines
|
|
- Rust: Unit tests for core logic; add integration tests for API calls. Run with `cargo test`. Organize tests near code or in `tests/`.
|
|
- Julia: Validate transformations and plots visually; keep scripts deterministic.
|
|
- Quarto: Manually review rendered HTML for links, figures, and warnings.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Commits: Use clear, conventional messages (e.g., `feat:`, `fix:`, `docs:`). Scope small and focused.
|
|
- PRs: Provide description, linked issues, steps to validate (commands), and screenshots of rendered docs when relevant.
|
|
|
|
## Security & Configuration
|
|
- Environment variables: `kagi_api_key`, `admin_api_key`. Export locally (e.g., `export admin_api_key=...`); never commit secrets.
|
|
- Dependencies: Keep minimal and up-to-date. Prefer configuration via env vars over hardcoded values.
|
|
|
|
## CI/CD & Deployment
|
|
- GitLab CI builds Docker, renders Quarto to static hosting; Rust runs separately for content sync. Avoid pipeline changes unless necessary; include rationale in PRs if modified.
|
|
|