# `pj`


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Installation

Install latest from the GitHub
[repository](https://github.com/kitled/pj):

``` sh
$ uv tool install git+https://github.com/kitled/pj.git
```

or from [pypi](https://pypi.org/project/pj/)

``` sh
$ uv tool install pj
```

## How to use `pj`

``` sh
pj init my-project  # start
pj sync             # work
pj kill             # end
```

Find all options with `--help` after any command.

``` sh
pj --help
pj init --help
```

### `init`

> Create new project

Start with `pj init proj_name` to create a GitHub repo, setup `nbdev`
fully, and push ready to code.

``` sh
pj init my-project -v \
 --desc "ML utilities" \
 --public \
 --python 3.12 \
 --license apache2
```

### `sync`

> Automated `nbdev_prepare`, `git commit` and `push`.

Use `pj sync` to update remote;  
flag `-m "commit message"` (default: “save”).

``` sh
pj sync -m "Add new feature"
```

### `kill`

> Stop all servers

`pj kill` will terminate all running Jupyter, nbdev, Quarto processes on
the host.

## Why `pj`?

### Purpose

Create a fully-configured GitHub + nbdev project with one command.  
No manual setup, no forgotten steps. From zero to ready-to-code.

### The Three Phases

1.  Checks - Validate prerequisites
2.  Setup - Create repo, nbdev structure, venv, kernel, direnv
3.  Sync - Prepare nbdev, commit, push

### Design Principles

- Clean output: One line per operation
- Verbose mode: Show commands and boxed output with `-v`
- Fail fast: Stop on first error
- Sensible defaults: Private repos, log to `init.log`, push immediately

## Devs

If you are new to using `nbdev` here are some useful pointers to get you
started.

### Install pj in Development mode

``` sh
# make sure pj package is installed in development mode
pip install -e .

# make changes under nbs/ directory
# ...

# compile to have changes apply to pj
nbdev_prepare
```

## Usage

### Documentation

Documentation can be found hosted on this GitHub
[repository](https://github.com/kitled/pj)’s
[pages](https://kitled.github.io/pj/). Additionally you can find package
manager specific guidelines on [conda](https://anaconda.org/kitled/pj)
and [pypi](https://pypi.org/project/pj/) respectively.
