From b8699a1c4051cec475c0f42eabeb35236dbe4a38 Mon Sep 17 00:00:00 2001 From: Chris Pryer Date: Sat, 4 May 2024 11:52:46 -0400 Subject: [PATCH] Remove old docs --- README.md | 2 - docs/CONTRIBUTING.md | 10 -- docs/development.md | 56 -------- docs/index.md | 11 -- docs/user_guide.md | 295 ------------------------------------------- 5 files changed, 374 deletions(-) delete mode 100644 docs/development.md delete mode 100644 docs/index.md delete mode 100644 docs/user_guide.md diff --git a/README.md b/README.md index c527dbfd..4372499c 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,6 @@ The goal is to create an opinionated tool to support a reliably inviting onboard ## Installation -WARNING: The PyPI distribution is outdated. See from source install using Cargo. - ``` pip install huak ``` diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3de261ee..32977400 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -4,10 +4,6 @@ We appreciate your interest in contributing to our project! You can contribute to Huak by checking for unassigned issues or even just documenting features and bugs by creating new issues. -## Communication - -You can reach out on discord in our [discord server](https://discord.gg/St3menxFZT) if you have any questions. Otherwise, please feel free to [open an Issue](https://github.com/cnpryer/huak/issues/new/). - ## Testing Use cargo to run the tests. @@ -23,9 +19,3 @@ Note that on Windows the tests may run slower than on other systems. We follow the standard [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) when making contributions to Huak. **Make sure to communicate your interest prior submitting a PR by ussing Issues. You can create one [here](https://github.com/cnpryer/huak/issues/new).** - -## Commits - -✨ Please practice clean commit hygiene. - -TODO: See [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for more. diff --git a/docs/development.md b/docs/development.md deleted file mode 100644 index ab5921e1..00000000 --- a/docs/development.md +++ /dev/null @@ -1,56 +0,0 @@ -# Contents - -- [Contributing](#contributing) -- [Project Workflows](#project-workflows) -- [The Code](#the-code) - -## Contributing - -See [CONTRIBUTING.md](/docs/CONTRIBUTING.md). - -## Project workflows - -Huak enables and supports a standard *process of developing*. This process is linear. Iteration happens in sequential steps. - -```mermaid -graph LR - A[Project Bootstrap] --> B[Project Setup] - B --> C[Project Change] - C --> D[Project Test] - D --> E[Project Distribution] -``` - -### 1. Project Bootstrap - -Quick and easy initialization of a project with opinions on topics like structure and configuration. - -### 2. Project Setup - -Adding dependencies, various metadata, etc. The setup phase is vague but prepares the project for the following steps. - -### 3. Project Change - -A change is made to the project. - -### 3. Project Test - -The project is evaluated in some form. - -### 4. Project Distribution - -The project is distributed for use. This can be publishing to a registry or simply using it locally and executing within its context. - -## The Code - -Currently, the project is structured using the following crates: - -```bash -crates -├── `huak-cli` # Huak's CLI -├── `huak-dev` # Huak's development library -├── `huak-home` # Huak's home library -├── `huak-package-manager` # Huak's package management library -├── `huak-python-manager` # Huak's python management library -├── `huak-toolchain` # Huak's toolchain management library -└── `huak-workspace` # Huak's workspace library -``` diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index a0b83406..00000000 --- a/docs/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Huak - -A Python package manager written in Rust inspired by Cargo. - -!!! Warning - `huak` is in an experimental state. - -## Contents - -* [User Guide](./user_guide.md) - diff --git a/docs/user_guide.md b/docs/user_guide.md deleted file mode 100644 index a868c26e..00000000 --- a/docs/user_guide.md +++ /dev/null @@ -1,295 +0,0 @@ -# User Guide - -!!! Warning - `huak` is in an experimental state. - -## Contents - -1. [Getting started](#getting-started) -1. [Manage your dependencies](#manage-your-dependencies) -1. [Support more of your workflow](#support-more-of-your-workflow) -1. [Distribute your project](#distribute-your-project) -1. [Configure Huak](#configure-huak) - -## Getting started - -### Installation - -Use `pip` to install `huak` from [PyPI](https://pypi.org). - -```zsh -~/github -❯ pip install huak -``` - -### Create a new project - -To create a new project use the `new` command. - -```zsh -~/github took 2s -❯ huak new my-project -``` - -### Or initialize an existing project - -```zsh -~/github/existing-project -❯ huak init -``` - -`huak` distinguishes between library and application-like projects. Projects default to the library type if a type isn't specified. Specify the type with either the `--lib` or `--app` flag. - -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 -❯ tree . -. -├── pyproject.toml -├── src -│   └── my_project -│   └── __init__.py -└── tests - └── test_version.py -``` - -!!! note - Without `--no-vcs` `huak` generates a `git`-initialized project. - -## Manage your dependencies - -### Add a dependency - -Use `huak` to add dependencies to your Python project. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak add xlcsv -``` - -#### Installer Options - -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 -❯ huak add torch torchvision torchaudio -- --extra-index-url https://download.pytorch.org/whl/cu117 -``` - -`huak` will add the packages to your pyproject.toml, so passing [PEP 508](https://peps.python.org/pep-0508/) strings would help persist this behavior for future installs. - -!!! Tip - You can also assign dependencies to a group using `--group`. - -### Install dependencies listed in the pyproject.toml - -Use the `install` command to install the project's dependencies. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak install -``` - -#### Using --groups - -To install just "required" dependencies: - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak install --groups required -``` - -If you already have an optional dependency group named "required" then `--groups` will operate as normal and only install the groups provided. - -### Update dependencies - -To update a dependency use the `update` command. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak update xlcsv -``` - -Or everything. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak update -``` - -### Remove dependencies - -To remove a dependency from the project use the `remove` command. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak remove xlcsv -``` - -## Support more of your workflow - -Huak ships commands allowing you to format your python code, lint it, and test it. - -### Format your code - -Use the `fmt` command to format your Python project's code. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak fmt -``` - -#### Using --check - -!!! Warning - As of `v0.0.20` `huak` no longer uses `black`. - -Use `--check` if all you want to do is verify your code is already formatted. Note that `huak` currently uses `ruff` to format your code. This means that `--` can only pass options to `ruff`. Use the `[tool.ruff]` for more configuration. - -!!! Warning - `huak` will exit prior to running with `--check` if your imports are not sorted. See [#510](https://github.com/cnpryer/huak/issues/510) for the status of this issue. - -### Lint your code - -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 -❯ huak lint -``` - -The `--fix` flag can be used to address any auto-fixable issues. - -`huak` wraps tools like `ruff` for some of its commands. To configure a wrapped tool such as `ruff` use the pyproject.toml file: - -```toml -[tool.ruff] -# ... -``` - -`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 -❯ huak lint --no-types -``` - -!!! Note - Currently, since `ruff` is the default tool used by `huak lint`, passing additional options with `--` is reserved for `ruff`. To configure `mypy` use the `[tool.mypy]` approach. This limitation will be addressed in future versions of `huak` (see [#505](https://github.com/cnpryer/huak/issues/505)). - -### Test your code - -Use the `test` command to test your project. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak test -``` - -### Run commands within your project's environment context - -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 -❯ 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 - 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. - -## Manage your Python installations - -By default `huak` will use the first Python interpreter found from your `PATH` environment variable. You can `list` these by using the `python` command. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak python list -1: /Users/chrispryer/.pyenv/shims/python3.11 -2: /Users/chrispryer/.pyenv/shims/python3.10 -... -``` - -So `huak` would use `/Users/chrispryer/.pyenv/shims/python3.11` out of the box. You can use a different installed Python version with `use`. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak python use 3.10 -``` - -## 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 -❯ huak build - -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak publish -``` - -### Cleaning up - -Use `huak clean` to clean out the dist/ directory. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 took 26s -❯ huak clean -``` - -## Configure Huak - -### Configure shell completion - -With `huak completion` you can setup shell completion for `huak`. - -```zsh -my-project on master 📦 v0.0.1 via 🐍 v3.11.0 -❯ huak completion -h -Generates a shell completion script for supported shells. See the help menu for more information on supported shells - -Usage: huak completion [OPTIONS] - -Options: - -s, --shell [possible values: bash, elvish, fish, powershell, zsh] - -u, --uninstall Uninstalls the completion script from your shell init file. If this flag is passed the --shell is required - -h, --help Print help -``` - -Add `huak completion --shell ` to your shell's initialization to use this feature. - -```zsh -eval "$(huak completion --shell )" -``` - -## Providing feedback - -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 -❯ huak --version -huak 0.0.19 -``` - -*Use the [0.0.16 User Guide](https://github.com/cnpryer/huak/blob/9b2bee0ac3425898394b3d9273105f554c45a744/docs/user_guide.md) for `huak` versions prior to `v0.0.19`.*