Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@cnpryer
cnpryer committed Mar 30, 2023
1 parent 2591fde commit 5d5bfbe
Show file tree
Hide file tree
Showing 2 changed files with 57 additions and 38 deletions.
35 changes: 18 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,23 +47,24 @@ A Python package manager written in Rust inspired by Cargo.
Usage: huak [OPTIONS] <COMMAND>

Commands:
add Add dependencies to the project
build Build tarball and wheel for the project
config Interact with the configuration of huak
clean Remove tarball and wheel from the built project
fix Auto-fix fixable lint conflicts
fmt Format the project's Python code
init Initialize the existing project
install Install the dependencies of an existing project
lint Lint the project's Python code
new Create a new project at <path>
publish Builds and uploads current project to a registry
remove Remove dependencies from the project
run Run a command within the project's environment context
test Test the project's Python code
update Update the project's dependencies
version Display the version of the project
help Print this message or the help of the given subcommand(s)
activate Activate the virtual envionrment
add Add dependencies to the project
build Build tarball and wheel for the project
config Interact with the configuration of huak
clean Remove tarball and wheel from the built project
fix Auto-fix fixable lint conflicts
fmt Format the project's Python code
init Initialize the existing project
install Install the dependencies of an existing project
lint Lint the project's Python code
new Create a new project at <path>
publish Builds and uploads current project to a registry
remove Remove dependencies from the project
run Run a command within the project's environment context
test Test the project's Python code
update Update the project's dependencies
version Display the version of the project
help Print this message or the help of the given subcommand(s)

Options:
-q, --quiet
Expand Down
60 changes: 39 additions & 21 deletions docs/user_guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ To create a new project use the `new` command.
Initializing an existing project adds a `pyproject.toml` to the current directory. Bootstrapping the project with the `new` command creates a Python project with the following structure:

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ tree .
.
├── pyproject.toml
Expand All @@ -60,7 +60,7 @@ Note that without `--no-vcs` `huak` generates a `git`-initialized project.
Use `huak` to add dependencies to your Python project.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak add xlcsv
```

Expand All @@ -69,7 +69,7 @@ my-project on  master 📦 v0.0.1 via 🐍 v3.11.0
Currently `huak` uses `pip` under the hood for package installation. You can pass additional arguments onto `pip`. Any arguments after `--` are handed off to `pip install`.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak add torch torchvision torchaudio -- --extra-index-url https://download.pytorch.org/whl/cu117
```

Expand All @@ -82,7 +82,7 @@ You can also assign dependencies to a group using `--group`.
Use the `install` command to install the project's dependencies.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak install
```

Expand All @@ -91,7 +91,7 @@ my-project on  master 📦 v0.0.1 via 🐍 v3.11.0
To install all dependencies (including optional dependencies) use the group name "all".

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak install --groups all
```

Expand All @@ -102,10 +102,10 @@ If you already have an optional dependency group named "all" then `--groups` wil
`huak install` would trigger a standard `pip install` on your group's packages. So without PEP 508 you won't install the pytorch.org packages as demonstrated with `huak add` earlier. To do this you could pass the same options given to `huak add`. Use a group to isolate these options to those specific dependencies.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak add torch torchvision torchaudio --group torch -- --extra-index-url https://download.pytorch.org/whl/cu117

my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak install --groups torch -- --extra-index-url https://download.pytorch.org/whl/cu117
```

Expand All @@ -116,21 +116,21 @@ In the future `huak` will manage translating installer options to PEP 508 string
To update a dependency use the `update` command.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak update xlcsv
```

You can also update a group of dependencies using `--group`.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak update --group dev
```

Or everything with "all".

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak update --group all
```

Expand All @@ -139,7 +139,7 @@ my-project on  master 📦 v0.0.1 via 🐍 v3.11.0
To remove a dependency from the project use the `remove` command.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak remove xlcsv
```

Expand All @@ -152,7 +152,7 @@ Huak ships commands allowing you to format your python code, lint it, and test i
Use the `fmt` command to format your Python project's code.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak fmt
```

Expand All @@ -167,7 +167,7 @@ Use `--check` if all you want to do is verify your code is already formatted. No
Use the `lint` command to lint your Python project's code.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0 took 2s
my-project on master 📦 v0.0.1 via 🐍 v3.11.0 took 2s
❯ huak lint
```

Expand All @@ -183,7 +183,7 @@ The `--fix` flag can be used to address any auto-fixable issues.
`huak` also uses `mypy` for type-checking. To disable this behavior use `--no-types`.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0 took 2s
my-project on master 📦 v0.0.1 via 🐍 v3.11.0 took 2s
❯ huak lint --no-types
```

Expand All @@ -194,7 +194,7 @@ Currently, since `ruff` is the default tool used by `huak lint`, passing additio
Use the `test` command to test your project.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak test
```

Expand All @@ -203,22 +203,40 @@ my-project on  master 📦 v0.0.1 via 🐍 v3.11.0
You can use `huak` to run a command within the Python environment your project uses.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak run which python
/Users/chrispryer/github/my-project/.venv/bin/python
```

### Activate the virtual environment

`huak` also implements an `activate` command to activate a virtual environment.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak activate
(.venv) bash-3.2$
```

Note that currently `huak` just runs `bash --init-file` on unix systems and uses `powershell` on Windows.

```powershell
(.venv) PS C:\Users\chris\github\my-project>
```

See [#486](https://github.com/cnpryer/huak/issues/486) for the status on the `activate` command.

## Distribute your project

### Publish to PyPI

If you're building a Python package you'd like to share, use `huak build` and `huak publish` to build and publish the project to [PyPI](https://pypi.org).

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak build

my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak publish
```

Expand All @@ -227,7 +245,7 @@ my-project on  master 📦 v0.0.1 via 🐍 v3.11.0
Use `huak clean` to clean out the dist/ directory.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0 took 26s
my-project on master 📦 v0.0.1 via 🐍 v3.11.0 took 26s
❯ huak clean
```

Expand All @@ -240,7 +258,7 @@ Use `huak config` commands to configure `huak`.
With `huak config completion` you can setup shell completion for `huak`.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak config completion -h
Generates a shell completion script for supported shells. See the help menu for more information on supported shells

Expand All @@ -258,7 +276,7 @@ Options:
Any bugs or suggestions can be submitted as issues [here](https://github.com/cnpryer/huak/issues/new). All feedback is welcome and greatly appreciated ❤️.

```zsh
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
my-project on master 📦 v0.0.1 via 🐍 v3.11.0
❯ huak --version
huak 0.0.10-alpha.6
```

0 comments on commit 5d5bfbe

Please sign in to comment.