Skip to content

Commit

Permalink
Documentation (#25)
Browse files Browse the repository at this point in the history
  • Loading branch information
@trappitsch
trappitsch authored Mar 10, 2024
1 parent 10a893b commit 0d2fdd4
Show file tree
Hide file tree
Showing 12 changed files with 505 additions and 50 deletions.
20 changes: 20 additions & 0 deletions .readthedocs.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.12"

mkdocs:
configuration: mkdocs.yml

# install package via pip
python:
install:
- requirements: requirements.lock
58 changes: 10 additions & 48 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,23 @@
# box

[![Rye](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/mitsuhiko/rye/main/artwork/badge.json)](https://rye-up.com)
[![Docs](https://readthedocs.org/projects/box/badge/?version=latest)](https://box.readthedocs.io/en/latest/?badge=latest)
[![tests](https://github.com/trappitsch/box/actions/workflows/tests.yml/badge.svg)](https://github.com/trappitsch/box/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/trappitsch/box/graph/badge.svg?token=CED96ANLRR)](https://codecov.io/gh/trappitsch/box)
[![Rye](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/mitsuhiko/rye/main/artwork/badge.json)](https://rye-up.com)

The goal of this package is
to provide a command line interface
that allows you to easily package your existing python project
with [`PyApp`](https://ofek.dev/pyapp/).

**Important:** This package is still in a very early
Currently, `box` only support python projects that have their metadata stored in a `pyproject.toml` file.
See [here](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#writing-pyproject-toml)
for details.

**Note**:
This package is still in a very early
development phase! Please report your findings and issues,
so that we can improve this tool together.

## Pre-requisites

In order to run `box`, you must have `cargo` installed.
Instructions to do so can be found
[here](https://doc.rust-lang.org/cargo/getting-started/installation.html).

Furthermore, we currently only support `rye` build environments,
however, support for more builders is planned for the near future.

## Installation

Install this tool using `pipx`:

pipx install git+https://github.com/trappitsch/box.git

## Usage

### Initialize a project

From within your project directory, run:

```
box init
```

The initialization will ask your for your script entry point.
We automatically read `[project.scripts]` and `[project.gui-scripts]`
to propose some values to select from.
However, you can also type your own entry point.
This is the entry point that will be set in `PyApp`
using the `PYAPP_EXEC_SPEC` environment variable.
Details can be found [here](https://ofek.dev/pyapp/latest/config/#execution-mode).

### Packaging

To package your project, run:

```
box package
```

This will first build your project using `rye`.
Then, the latest `PyApp` source will be downloaded and unpacked.
Finally, the project will be packaged with `PyApp` using `cargo`.

You can find the executable in the `target/release` directory.
Please refer to the [documentation](https://box.readthedocs.io/)
for further information on installation and usage.
35 changes: 35 additions & 0 deletions docs/.includes/build.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
=== "rye"

```
rye build --out dist --sdist
```

=== "hatch"

```
hatch build -t sdist
```

=== "pdm"

```
pdm build --no-wheel -d dist
```

=== "build"

Linux / macos:
```
python -m build --sdist --outdir dist
```

Windows:
```
py -m build --sdist --outdir dist
```

=== "flit"

```
flit build --format sdist
```
49 changes: 49 additions & 0 deletions docs/.includes/install.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
=== "pipx"

To install with `pipx`, type:

```
pipx install box
```

Alternatively, you can install the latest version directly from the GitHub repo.
This is only recommended if you want the latest tweaks.
For a production environment, please use the official releases.

```
pipx install git+https://github.com/trappitsch/box.git
```

=== "rye"

To install box as a `rye` tool, type:

```
rye install box
```

Alternatively, you can install the latest version directly from the GitHub repo.
This is only recommended if you want the latest tweaks.
For a production environment, please use the official releases.

```
rye install --git https://github.com/trappitsch/box.git box
```

=== "pip"

We do not recommend installing `box` with `pip`,
however, if have to do so for some reason,
install it via:

```
pip install box
```

Alternatively, you can install the latest version directly from the GitHub repo.
This is only recommended if you want the latest tweaks.
For a production environment, please use the official releases.

```
pip install git+https://github.com/trappitsch/box.git
```
13 changes: 13 additions & 0 deletions docs/cli.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# CLI documentation

Below is the automatically generated docummentation for `box`.
You can also find this by typing `box --help` in your terminal.



::: mkdocs-click
:module: box.cli
:command: cli
:prog_name: box
:depth: 1
:style: table
96 changes: 96 additions & 0 deletions docs/guide.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Detailed usage guide for `box`

Below are some detailed information on how to use `box`.
Note that you can always get help by typing `box -h` on the command line,
or by typing `box COMMAND -h` to obtain help for a specific command.

## Initialization

After you have installed `box`, navigate to the folder of your project.
Then, type

```
box init
```

This will start the initialization process of your project.
The initialization will ask you questions, unless the `-q`/`--quiet` flag is set.
If this flag is set, default values or user provided arguments will be used.

The following table shows a list of questions, their default values, their arguments to provide answers in quiet mode, and an explanation:

| Question | Default | Argument | Explanation |
|----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Choose a builder tool for the project | `rye` | `-b`<br> `--builder` | *Required:* The builder to use to package your pyproject file. Valid tools are `rye`, `hatch`, `pdm`, `build`, and `flit`. Ensure that the builder is available in the environment in which you run box. |
| Provide any optional dependencies for the project. | `None` | `--opt`<br>`--optional-deps` | *Optional:* Set any optional dependencies for the project. These are the dependencies that you would install in square brackets, e.g., via `pip install package_name[optional]`. If there are no optional dependencies, just hit enter. |
| Please type an app entry for the project or choose one from the list below | First entry in `pyproject.toml` for `[project.gui-scripts]`, if not available, then for `[project.scripts]`. If no entry points are given, the default value is set to `package_name:run`. | `-e`<br>`--entry` | *Required:* The entry point for the application. This is the command that will be used to start the application. If you have a `pyproject.toml` file, `box` will try and read potential entry points that you can select by passing it the digit of the list. You can also provide an entry point manually by typing it here. |
| Choose an entry type for the project. | `spec` | `-et`<br>`--entry-type` | *Required:* This specifies the type of the entry point that `PyApp` will use. `spec` (default) is an object reference, `module` for a python module, `script` for a python script, and `notebook` for a jupyter notebook. Details can be found [here](https://ofek.dev/pyapp/latest/config/#execution-mode). |
| Choose a python version to package the project with. | `3.12` | `--py`<br>`--python-version` | *Required:* The python version to package with your project. You can choose any python version from the list. More details can be found on the `PyApp` website [here](https://ofek.dev/pyapp/latest/config/#python-distribution). |
| Optional PyApp variables | `None` | `--opt-pyapp-vars` | *Optional:* Set any optional environmental variables that you can use in `PyApp` here by giving a list of variable name followed by the value for that variable. Note that the total number of arguments must be even. See the [`PyApp` documentation](https://ofek.dev/pyapp) for more information. If there are no optional variables, just hit enter. |

If you provided all the answers, your project should have been successfully initialized and print an according message.

!!! tip
While the recommended way to initialize a `box` project is simply to go through the questions that are asked
during a `box init`, you can go through initialization in `-q`/`--quiet` mode.
To still specify variables, just set them using the arguments discussed in the table above.
And if you are happy with all the defaults, you should be good to do.

## Packaging

To package your project, simply run:

```
box package
```

For verbose packaging, add the flag `-v` or `--verbose`.

This will take a bit of time and no output from building / packaging will be printed in non-verbose mode.
The following steps will be executed:

1. The project will be built using the selected builder.
2. The latest `PyApp` source will be downloaded and unpacked from GitHub.
3. The project will be packaged with `PyApp` using `cargo`.
4. The executable will be placed in the `target/release` directory and renamed to your package name.


!!! abstract "Building the python project"

The python project will be built using the following command:

{% include-markdown ".includes/build.md" %}

This will put tye `.tar.gz` file of your project, which will then be packaged with `PyApp` into the `dist` folder.

### Local `PyApp` source

If you would like to provide a local `PyApp` source,
you can do so by providing either the path to the local `.tar.gz` source
or to a local folder using the `-p`/`--pyapp-source` argument.
The local source will then be used instead of the latest release from GitHub.
It will be copied into the `build` folder before packaging.

## Cleaning your project

If you want to clean the project, run:

```
box clean
```

By default, this will delete the `dist`, `build`, and `release` folder.
See the [CLI documentation](cli.md) for more information on the `clean` command,
e.g., if you only want to clean a specific subfolder.

## Remove the initialization

If you want to uninitialize the project,
type:

```
box uninit
```

This will remove the `[tool.box]` section from your `pyproject.toml` file.
If you provide the `-c`/`--clean` flag as well, the `dist`, `build`, and `release` folders will be deleted prior to uninitializing.
77 changes: 77 additions & 0 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Welcome to `box`

[![Docs](https://readthedocs.org/projects/box/badge/?version=latest)](https://box.readthedocs.io/en/latest/?badge=latest)
[![tests](https://github.com/trappitsch/box/actions/workflows/tests.yml/badge.svg)](https://github.com/trappitsch/box/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/trappitsch/box/graph/badge.svg?token=CED96ANLRR)](https://codecov.io/gh/trappitsch/box)
[![Rye](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/mitsuhiko/rye/main/artwork/badge.json)](https://rye-up.com)

The goal of this package is
to provide a command line interface
that allows you to easily package your existing python project
with [`PyApp`](https://ofek.dev/pyapp/).

Currently, `box` only support python projects that have their metadata stored in a `pyproject.toml` file.
See [here](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#writing-pyproject-toml)
for details.

!!! warning
This package is still in a very early
development phase! Please report your findings and issues,
so that we can improve this tool together.

## Issues, comments, contributions,...

We welcome contributions to this project.
If you run into any problem, want to suggest a feature, want to contribute, or just want to say hi,
please feel free to open an issue on [GitHub](https://github.com/trappitsch/box/issues)
or to start a new [discussion](https://github.com/trappitsch/box/discussions).

## Pre-requisites

In order to run `box`, you must have `cargo` installed.
Instructions to do so can be found
[here](https://doc.rust-lang.org/cargo/getting-started/installation.html).


## Installation

!!! failure

The installation from `pypi` (top part from given options below) is currently not available.
If you want to test this project, please use the installation from github.

!!! abstract "Installation Instructions"

{% include-markdown ".includes/install.md" %}


## Usage - the short version

### Initialize a project

From within your project directory, run:

```
box init
```

This will ask you a few questions, answer them, and you will be done.

### Packaging

To package your project, run:

```
box package
```

This will first build your project using. the selected builder.
Then, the latest `PyApp` source will be downloaded and unpacked.
Finally, the project will be packaged with `PyApp` using `cargo`.

You can find the executable in the `target/release` directory.

### Further resources

- [CLI overview documentation](cli.md)
- [Detailed usage guide](guide.md)
Loading

0 comments on commit 0d2fdd4

Please sign in to comment.