55By design, pyprefab requires only a few pieces of information to create the
66boilerplate for a Python package.
77
8- ``` bash
9- ➜ pyprefab --help
10-
11- Usage: pyprefab [OPTIONS] NAME
12-
13- 🐍 Create Python package boilerplate 🐍
14-
15- ╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
16- │ * name TEXT Name of the project │
17- │ [required] │
18- ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
19- ╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
20- │ * --author TEXT Project author │
21- │ [required] │
22- │ * --description TEXT Project description │
23- │ [required] │
24- │ * --dir PATH Directory that will contain the project │
25- │ [required] │
26- │ --help Show this message and exit. │
27- ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
8+ ``` sh
9+ >>> pyprefab --help
10+
11+ Usage: pyprefab [OPTIONS] NAME
12+
13+ 🐍 Create Python package boilerplate 🐍
14+
15+ ╭─ Arguments ───────────────────────────────────────────────────────────────╮
16+ │ * name TEXT Name of the project [required] │
17+ ╰───────────────────────────────────────────────────────────────────────────╯
18+ ╭─ Options ─────────────────────────────────────────────────────────────────╮
19+ │ * --author TEXT Project author [required] │
20+ │ * --description TEXT Project description [required] │
21+ │ * --dir PATH Directory that will contain the project [required] │
22+ │ --docs Include Sphinx documentation files │
23+ │ --help Show this message and exit. │
24+ ╰───────────────────────────────────────────────────────────────────────────╯
25+ ```
26+
27+ ### Example CLI use
28+
29+ To create a Python package named ` holodeck ` in a directory named
30+ ` trek/code/holodeck ` :
31+
32+ ``` sh
33+ >>> pyprefab holodeck --author rbarclay \
34+ >>> --description " personal holodeck programs"
35+ >>> --dir trek/code/holodeck
36+
37+ ╭────────────── Project Created Successfully ────────────────╮
38+ │ Created new project holodeck in trek/code/holodeck │
39+ │ Author: rbarclay │
40+ │ Description: personal holodeck programs │
41+ ╰────────────────────────────────────────────────────────────╯
42+ ```
43+
44+ The pyprefab command above creates scaffolding for the new ` holodeck ` package,
45+ with the following files in ` trek/code/holodeck ` :
46+
47+ ``` sh
48+ .
49+ ├── .github
50+ │ └── workflows
51+ │ ├── ci.yaml
52+ │ ├── publish-pypi-test.yaml
53+ │ └── publish-pypi.yaml
54+ ├── .gitignore
55+ ├── .pre-commit-config.yaml
56+ ├── CHANGELOG.md
57+ ├── CONTRIBUTING.md
58+ ├── README.md
59+ ├── pyproject.toml
60+ ├── src
61+ │ └── holodeck
62+ │ ├── __init__.py
63+ │ └── app.py
64+ └── test
65+ └── test_app.py
2866```
2967
30- For example:
68+ :::{caution}
69+ If the ` --dir ` option points to a non-empty directory, pyprefab will overwrite
70+ the existing contents (after prompting you).
71+ :::
72+
73+ ### Optional project documentation
74+
75+ Pass the ` --docs ` option to pyprefab to include Sphinx-based documentation files
76+ with the new package.
3177
3278``` sh
33- pyprefab project_test --author lassie --description " this is a pet project for lassie" ~ /code/lassie
79+ >>> pyprefab holodeck --author rbarclay \
80+ >>> --description " personal holodeck programs"
81+ >>> --dir /users/becky/code/trek/code/holodeck \
82+ >>> --docs
3483```
3584
36- If you don't explicitly pass the ` --author ` , ` --description ` , and ` --dir ` options,
37- pyprefab will prompt you for them:
85+ This option adds a ` docs ` directory to the code base:
3886
3987``` sh
40- ➜ pyprefab project_test
41- Project author: lassie
42- Project description: this is a pet project for lassie
43- Project directory: /Users/dogs/code/lassie
88+ .
89+ ├── .github
90+ │ └── workflows
91+ │ ├── ci.yaml
92+ │ ├── publish-pypi-test.yaml
93+ │ └── publish-pypi.yaml
94+ ├── .gitignore
95+ ├── .pre-commit-config.yaml
96+ ├── CHANGELOG.md
97+ ├── CONTRIBUTING.md
98+ ├── README.md
99+ ├── docs
100+ │ └── source
101+ │ ├── CHANGELOG.md
102+ │ ├── CONTRIBUTING.md
103+ │ ├── README.md
104+ │ ├── _static
105+ │ │ └── custom.css
106+ │ ├── conf.py
107+ │ ├── index.rst
108+ │ └── usage.md
109+ ├── pyproject.toml
110+ ├── src
111+ │ └── holodeck
112+ │ ├── __init__.py
113+ │ └── app.py
114+ └── test
115+ └── test_app.py
116+ ```
117+
118+ ### Interactive mode
119+
120+ If you don't explicitly pass the ` --author ` , ` --description ` , ` --dir ` options,
121+ pyprefab will prompt for them:
122+
123+ ``` sh
124+ >>> pyprefab holodeck --docs
125+ Project author: rbarclay
126+ Project description: personal holodeck programs
127+ Project directory: trek/code/holodeck/docs
128+
129+ ╭──────────── Project Created Successfully ─────────────╮
130+ │ Created new project holodeck in trek/code/holodeck │
131+ │ Author: rbarclay │
132+ │ Description: personal holodeck programs │
133+ │ Documentation: trek/code/holodeck/docs │
134+ ╰───────────────────────────────────────────────────────╯
44135```
45136
46137## Creating a dev environment for the new package
@@ -64,32 +155,51 @@ These directions use `uv`, but you can use your preferred tooling.
64155 uv run < your_package_name>
65156 ` ` `
66157
67- You should see a log output stating that the project has been set up correctly.
158+ You should see log output stating that the project has been set up correctly.
68159
69160 For example:
70- ` 2025-01-13 02:29:08 [info ] project_test successfully created.`
161+
162+ ` ` ` sh
163+ 2025-01-13 02:29:08 [info] project_test successfully created.
164+ ` ` `
71165
72166 You can also run the tests:
73167
74168 ` ` ` sh
75169 uv run pytest
76170 ` ` `
77171
78- ** Optional: **
172+ # ## Previewing documentation
79173
80- - Add the new project to a git repository:
174+ If your project includes the optional Sphinx documentation, make sure you can
175+ build and preview the docs before updating them:
81176
82- ` ` ` sh
83- git init
84- git add .
85- git commit -am " Initial commit"
86- ` ` `
177+ ` ` ` sh
178+ uv run --group docs sphinx-autobuild docs/source docs/_build/html
179+ ` ` `
87180
88- - If you use [pre-commit](https://pre-commit.com/), pyprefab' s boilerplate
89- includes a baseline `pre-commit-config.yaml` configuration. To use it, make
90- sure the project has been added to git (see above) and run the following
91- command to install the pre-commit git hook scripts:
181+ The output of the above command provides a URL for viewing the documentation
182+ via a local server (usually http://127.0.0.1:8000).
92183
93- ```sh
94- pre-commit install
95- ```
184+ ` ` ` sh
185+ The HTML pages are in docs/_build/html.
186+ [sphinx-autobuild] Serving on http://127.0.0.1:8000
187+ [sphinx-autobuild] Waiting to detect changes...
188+ ` ` `
189+
190+ # ## Adding the project to git
191+
192+ To create a new git repository for the project (this is optional):
193+
194+ ` ` ` sh
195+ git init
196+ git add .
197+ git commit -am " Initial commit"
198+ ` ` `
199+
200+ :::{tip}
201+ If you use [pre-commit](https://pre-commit.com/), pyprefab' s boilerplate
202+ includes a baseline `pre-commit-config.yaml` configuration. To use it, make
203+ sure the project has been added to git (see above) and install the pre-commit
204+ hooks: `pre-commit install`
205+ :::
0 commit comments