# pj


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

Three methods to create, sync, and release projects:

1.  **`Project.new()`** Create repo on GitHub + local clone. If `nbdev`:
    add theme toggle, set GH Pages branch.
2.  **[`Project.sync()`](https://1iis.github.io/pj/core.html#project.sync)**
    (opt. `nbdev_prepare`) → `commit` → `pull --rebase` → `push`.
3.  **[`Project.ship()`](https://1iis.github.io/pj/core.html#project.ship)**
    Version bump → `tag` → GitHub release. If `PyPI=True`: build →
    upload.

Works with any repo to handle lifecycle with
[Git](https://git-scm.com/), [GitHub](https://github.com/), and
[PyPI](https://pypi.org/).  
Notebook-friendly, whether [Jupyter](https://jupyter.org/),[1]
[`nbdev`](https://nbdev.fast.ai/), or [SolveIT](https://solve.it.com/)!
📚💙

Built with [`fastgit`](https://github.com/AnswerDotAI/fastgit/) (git
operations), [`ghapi`](https://github.com/AnswerDotAI/ghapi/) (GitHub
API), and [`fastcore`](https://github.com/AnswerDotAI/fastcore/)
(utilities).

## Install

This has only been tested in SolveIT, with the `nbs/00_core` dialog. You
may either:

- clone this repo and open `nbs/00_core` (or use `pj/core.py`)
- download `nbs/00_core` or view the shared dialog, and import it to
  your SolveIT instance.

More coming very soon.

``` python
# [coming soon] pip install pj-py
```

## Usage

Select Project \> sync to commit+push \> release.

### 0. API setup

Authenticate once. All
[`Project`](https://1iis.github.io/pj/core.html#project) instances share
the connection.

``` python
# imports not required if you run it from the 00_core dialog in SolveIT.
# Otherwise:
#from pj import Project, set_api
#from ghapi.all import GhApi

set_api(GhApi())
```

Check that it’s fine:

``` python
get_api()
```

### 1. Target project

Create a new project (A), or select an existing repo (B).

#### A. Create new

``` python
p = Project.new("mylib")
# = Project.new("mylib", path=None, org=None, desc=None, private=True, nbdev=False, verbose=False)
```

Creates a private GitHub repo under your user, clones it locally,
installs nbdev hooks. `org` takes the GH handle.

#### B. Select existing repo

``` python
p = Project("path/to/repo")
```

Auto-detects pj type and owner (`settings.ini` for nbdev, otherwise
`pyproject.toml`, or `other` if none).

### 2. Sync changes

``` python
p.sync()
# = p.sync(msg="sync")
```

Stages all, commits with message “sync”, pulls with rebase, pushes.

### 3. Release

``` python
p.ship()
# = p.ship(part=2, dry_run=False, force=False, pypi=False, quiet=False)
```

Bumps patch version (0.0.X), tags, creates GitHub release. No PyPI
upload by default.

## Utilities

`Project.` public methods:

- `ls()` to list files in the project’s repo.
- `setup_pages()` configures GitHub Pages manually.
- `dark_theme()` applies dark mode to nbdev docs.
- Any unknown method forwards to git.

## Troubleshooting

**Path errors**  
Reassign `p = Project("correct/path")` to fix the current working
directory (`cwd`).  
Restart kernel first if it still fails.

**Rebase conflicts**  
`p.g('rebase', '--abort')` to start over, or resolve and continue.

## API Summary

**Create:**

``` python
p = Project.new("mylib") # Private repo
```

``` python
p = Project.new(
    "mylib",
    org="myorg",         # GH Organization
    desc="Cool lib"      # About
    private=False,       # Public repository
    nbdev=True           # nbdev/Quarto GH Pages w. light/dark toggle
)
```

**Existing:**

``` python
p = Project('mylib')     # [cwd/]'relative/path' or '/absolute/path'
```

**Sync:**

``` python
p.sync()                 # Commit all, rebase, push
p.sync("Fix bug #42")    # Commit message (default: 'sync')
```

**Release:**

``` python
p.ship()                 # Bump patch, tag, GitHub release
p.ship(part=1)           # Bump minor
p.ship(pypi=True)        # Include PyPI upload
p.ship(dry_run=True)     # Preview without doing anything
```

**Utilities:**

``` python
p.ls()                   # List files (takes regex str)
p.ls('nbs')              # List notebooks ('py' for Python files)
p.setup_pages()          # Configure GitHub Pages manually
p.dark_theme()           # Enable Quarto dark mode w. toggle button (nbdev docs)
p.status()               # Git methods forward to p.g (thus fastgit.Git)
```

------------------------------------------------------------------------

<!-- here be dragons -->

[1] Jupyter+Quarto specific QoL to come soon™