Commit 4369c67
committed
docs(cli,repo): document pn init directory behavior
The getting-started walkthrough and the CONTRIBUTING snippet both left
you outside the project they had just created, and the CLI reference
bullet didn't say where a named project lands. Documents the two new
refusal messages in troubleshooting, following that file's convention of
one heading per literal error string.1 parent 0f68f82 commit 4369c67
4 files changed
Lines changed: 38 additions & 3 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -25,6 +25,7 @@ pn --help | |||
| 25 | 25 | ||
| 26 | 26 | # create a new sample app from the bundled templates | |
| 27 | 27 | pn init my_app | |
| 28 | + cd my_app | ||
| 28 | 29 | ||
| 29 | 30 | # run the Hello World example | |
| 30 | 31 | cd examples/hello-world && pn run android | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -7,8 +7,10 @@ the documented behavior never drifts from the code. | |||
| 7 | 7 | ## Subcommands | |
| 8 | 8 | ||
| 9 | 9 | - `pn init [name]`: scaffold a new project (creates `app/`, | |
| 10 | - `pythonnative.toml`, `.gitignore`). Flag: `--force` to overwrite | ||
| 11 | - existing files. See [Configuration](../guides/configuration.md). | ||
| 10 | + `pythonnative.toml`, `.gitignore`). With a name it creates `./<name>/` | ||
| 11 | + and scaffolds into it; without one it uses the current directory. | ||
| 12 | + Flag: `--force` to overwrite existing files or scaffold into a | ||
| 13 | + non-empty directory. See [Configuration](../guides/configuration.md). | ||
| 12 | 14 | - `pn doctor [android|ios]`: diagnose the local toolchain and validate | |
| 13 | 15 | `pythonnative.toml`. Exits non-zero when something will block a build. | |
| 14 | 16 | - `pn preview [component]`: render the app in a desktop (Tkinter) window | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -9,16 +9,20 @@ pn --help | |||
| 9 | 9 | ||
| 10 | 10 | ```bash | |
| 11 | 11 | pn init MyApp | |
| 12 | + cd MyApp | ||
| 12 | 13 | ``` | |
| 13 | 14 | ||
| 14 | - This scaffolds: | ||
| 15 | + This creates a `MyApp/` directory containing: | ||
| 15 | 16 | ||
| 16 | 17 | - `app/` with a minimal `main.py` | |
| 17 | 18 | - `pythonnative.toml`: your project configuration (app id, version, | |
| 18 | 19 | permissions, assets, and signing). See | |
| 19 | 20 | [Configuration](guides/configuration.md). | |
| 20 | 21 | - `.gitignore` | |
| 21 | 22 | ||
| 23 | + Run `pn init` without a name to scaffold into the current directory | ||
| 24 | + instead, named after it. | ||
| 25 | + | ||
| 22 | 26 | A minimal `app/main.py` looks like: | |
| 23 | 27 | ||
| 24 | 28 | ```python | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -28,6 +28,34 @@ is finding a different Python. Reactivate the venv or run | |||
| 28 | 28 | `pn init` won't clobber existing project files. Pass `--force` or | |
| 29 | 29 | remove the listed files first. | |
| 30 | 30 | ||
| 31 | + ### `Refusing to overwrite existing non-empty directory: my_app/` | ||
| 32 | + | ||
| 33 | + `pn init my_app` creates `my_app/` and scaffolds into it, so it stops | ||
| 34 | + when that directory already holds files. Pass `--force` to scaffold over | ||
| 35 | + it, choose a different name, or run `pn init` from inside the directory | ||
| 36 | + to use it as is. An existing but empty directory is fine. | ||
| 37 | + | ||
| 38 | + ### `Refusing to overwrite existing file: my_app` | ||
| 39 | + | ||
| 40 | + Something other than a directory is already at `./my_app`. `--force` | ||
| 41 | + won't help here, since `pn init` can't turn a file into a directory. | ||
| 42 | + Remove or rename it, or choose a different project name. | ||
| 43 | + | ||
| 44 | + ### `Refusing to treat a path as a project name: '../app'` | ||
| 45 | + | ||
| 46 | + `pn init` takes a single directory name, not a path, so the project always | ||
| 47 | + lands inside the current directory. Pass a plain name like `my_app`, or | ||
| 48 | + `cd` to the directory you want the project in and run `pn init` with no | ||
| 49 | + name at all. `--force` doesn't lift this one. | ||
| 50 | + | ||
| 51 | + ### `Refusing to scaffold through a link or outside the current directory: link` | ||
| 52 | + | ||
| 53 | + The name resolves somewhere other than a directory directly inside the | ||
| 54 | + current one, so `pn init` stops rather than writing through it. A symlink | ||
| 55 | + at `./link` is the usual cause. Scaffold into a real directory, or `cd` to | ||
| 56 | + the directory the link points at and run `pn init` with no name. `--force` | ||
| 57 | + doesn't lift this one either. | ||
| 58 | + | ||
| 31 | 59 | ### `Do not list 'pythonnative' in [requirements].packages` | |
| 32 | 60 | ||
| 33 | 61 | The CLI bundles the installed `pythonnative` package directly into | |
0 commit comments