trackforge 0.1.7

A unified, high-performance computer vision tracking library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# Contribution guidelines

First off, thank you for considering contributing to Trackforge.

If your contribution is not straightforward, please first discuss the change you wish to make by creating a new issue before making the change, or starting a discussion on GitHub.

## AI Generated Content

We welcome high quality PRs, whether they are human generated or made with the assistance of AI tools, but we ask that you follow these guidelines:

- **Attribution**: Tell us about your use of AI tools.
- **Review**: Make sure you review every line of AI generated content for correctness and relevance.
- **Quality**: AI-generated content should meet the same quality standards as human-written content.

## Pull requests

All contributions are welcome. Please include as many details as possible in your PR description.

### Keep PRs small, intentional, and focused

- Aim for PRs under 500 lines of changes when possible.
- Separate refactoring, formatting, and functional changes into different PRs.

### Code formatting

Run `cargo fmt` before committing to ensure that code is consistently formatted.

## Implementation Guidelines

### Setup

TL;DR: Clone the repo and build it using `cargo` (for Rust) or `maturin` (for Python).

```shell
git clone https://github.com/onuralpszr/trackforge.git
cd trackforge

# Pure Rust Development
cargo build
cargo test

# Python Development
# Ensure you are in a virtual environment
maturin develop
```

### Tests

- **Rust**: Run `cargo test` to execute unit and integration tests.
- **Python**: Run `pytest` (when available) to check Python bindings.

### Continuous Integration

We use GitHub Actions for CI where we perform the following checks:

- The code should compile on stable Rust.
- The tests should pass (`cargo test`).
- The code should be formatted (`cargo fmt`).
- The code should pass hygiene checks (`cargo clippy`).

You can check these locally:

```shell
cargo fmt --all -- --check
cargo clippy -- -D warnings
cargo test
```

## Documentation

We use a hybrid documentation strategy to serve both Python and Rust API docs in a single zensical site.

### Dependencies

- **Python**: `zensical`, `mkdocstrings[python]`, `maturin`
- **Rust**: `cargo-docs-md`
- **Rust Toolchain**: `nightly` (required for JSON output)

```bash
# Install Python deps
pip install zensical "mkdocstrings[python]" maturin

# Install Rust tool
cargo install cargo-docs-md
```

### Generating the Site

1. **Build Python Package**:
   ```bash
   maturin develop
   ```

2. **Generate Rustdoc JSON**:
   ```bash
   RUSTDOCFLAGS="-Z unstable-options --output-format json" cargo +nightly doc --no-deps
   ```

3. **Convert to Markdown**:
   ```bash
   mkdir -p docs/api
   cargo docs-md -p target/doc/trackforge.json -o docs/api --full-method-docs
   ```

4. **Fix Formatting**:
   Run the cleaning script to format tables and code blocks:
   ```bash
   python3 scripts/fix_docs.py
   ```

5. **Serve**:
   ```bash
   zensical serve
   ```
   Open http://127.0.0.1:8000.