Skip to content

Development Guide#

Technical guide for contributing code to PyGraft-gen.

On this page:

Development Setup#

Clone the repository and install in editable mode with development dependencies:

# Clone the project 
git clone https://github.com/Orange-OpenSource/pygraft-gen.git
cd pygraft-gen

# Create .venv & activate project
uv sync --group dev --group docs
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Clone the project 
git clone https://github.com/Orange-OpenSource/pygraft-gen.git
cd pygraft-gen

# Create .venv & activate project
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev,docs]"

# Clone the project 
git clone https://github.com/Orange-OpenSource/pygraft-gen.git
cd pygraft-gen

# Create .venv & activate project
poetry install --with dev --with docs
poetry run pygraft --version

Editable Install

Poetry and uv install in editable mode by default. With pip, use the -e flag. Editable mode means source code changes are immediately reflected without reinstalling.

Commit Convention#

Commits follow this format: <emoji> <type>(<scope>): <subject>

  • <emoji> is optional
<emoji> <type>(<scope>): <short imperative summary>
        ^----^  ^----^   ^------------------------^
        |       |        |
        |       |        +-> Subject: Summary in present tense (WHAT & WHY, not HOW)
        |       +----------> Scope: optional, specific module or area changed
        +------------------> Type: feat, fix, docs, style, refactor, perf, test, chore, etc.

Signed-off-by: git.user.name <git.user.email>

:sparkles: feat(core): add configuration file support

Implement support for reading settings from a config file.
- Enables environment-specific configuration
- Simplifies deployment and local setup

Signed-off-by: Mad Max <mad.max@example.com>

Commit Types#

Type Emoji Description
feat ✨ New feature
fix 🐛 Bug fix
docs 📝 Documentation only
style 🎨 Formatting/linting
refactor ♻ Code restructuring
perf ⚡ Performance improvement
test ✅ Add/update tests
chore 🔧 Maintenance/tooling
build 📦 Build system changes
ci ⚙ CI/CD configuration
revert 🔙 Revert previous commit

See more

Code Standards#

Our code quality is enforced by:

Example: 

def top_k(items: list[str], k: int) -> list[str]:
    """Return the first k items.

    Args:
        items: Input list.
        k: Number of items to return. Must be >= 0.

    Returns:
        The first k items, or all if len(items) < k.

    Raises:
        ValueError: If k is negative.
    """
    if k < 0:
        raise ValueError("k must be >= 0")
    return items[:k]

Documentation#

Our documentation uses MkDocs with the Material theme.

Start local development server: 

mkdocs serve --livereload

Open http://127.0.0.1:8000 in your browser. Changes auto-reload (refresh manually if needed).

Deployment

Documentation is automatically built and deployed via GitHub Actions. No manual build needed!

CLI Documentation

After modifying pygraft/cli.py, regenerate the CLI reference: 

typer pygraft.cli utils docs --name pygraft --output docs/reference/cli.md
Don't forget to commit the updated cli.md file!

Writing Style

Characters: Use ASCII or HTML entities only 

&rarr;  Correct
→       Wrong

Math: Use LaTeX notation 

Inline: $O(n)$
Block:  $$O(n)$$

External links: Always open in new tab 

[Text](https://example.com){target="_blank" rel="noopener"}

Callouts: Supported types from Material theme 

!!! note "Optional Title"
    Your content here

What's Next#