diff --git a/docs/docs/demo.md b/docs/docs/demo.md index 5ecae96503c..031a735113d 100644 --- a/docs/docs/demo.md +++ b/docs/docs/demo.md @@ -33,7 +33,7 @@ The source data used in the demo instance can be found on our [GitHub page](http ### Local Setup -If you wish to install the demo dataset locally (for initial testing), you can run the following command: +If you wish to install the demo dataset locally (for initial testing), you can run the following command (via [invoke](./start/invoke.md)): ```bash invoke dev.setup-test -i @@ -48,7 +48,7 @@ This will install the demo dataset into your local InvenTree instance. ### Clear Data -To clear demo data from your instance, and start afresh with a clean database, you can run the following command: +To clear demo data from your instance, and start afresh with a clean database, you can run the following command (via [invoke](./start/invoke.md)): ```bash invoke dev.delete-data diff --git a/docs/docs/develop/contributing.md b/docs/docs/develop/contributing.md index c5ffe22d779..bca21b483a0 100644 --- a/docs/docs/develop/contributing.md +++ b/docs/docs/develop/contributing.md @@ -40,6 +40,9 @@ invoke dev.setup-dev --tests Read the [InvenTree setup documentation](../start/intro.md) for a complete installation reference guide. +!!! note "Required Packages" + Depending on your system, you may need to install additional software packages as required. + ### Setup Devtools Run the following command to set up all toolsets for development. @@ -169,6 +172,7 @@ The various github actions can be found in the `./github/workflows` directory ### Run tests locally To run test locally, use: + ``` invoke dev.test ``` diff --git a/docs/docs/develop/react-frontend.md b/docs/docs/develop/react-frontend.md index 8843419ee47..1c4a525a765 100644 --- a/docs/docs/develop/react-frontend.md +++ b/docs/docs/develop/react-frontend.md @@ -9,7 +9,7 @@ The new UI requires a separate frontend server to run to serve data for the new ### Install -The React frontend requires its own packages that aren't installed via the usual invoke tasks. +The React frontend requires its own packages that aren't installed via the usual [invoke](../start/invoke.md) tasks. #### Docker @@ -18,7 +18,9 @@ Run the following command: This will install the required packages for running the React frontend on your InvenTree dev server. #### Devcontainer + !!! warning "This guide assumes you already have a running devcontainer" + !!! info "All these steps are performed within Visual Studio Code" Open a new terminal from the top menu by clicking `Terminal > New Terminal` diff --git a/docs/docs/faq.md b/docs/docs/faq.md index d8b51ecac65..98cd2cdb1b7 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -14,37 +14,17 @@ InvenTree installation is not officially supported natively on Windows. However ### Command 'invoke' not found -If the `invoke` command does not work, it means that the [invoke](https://pypi.org/project/invoke/) python library has not been correctly installed. +If the `invoke` command does not work, it means that the invoke tool has not been correctly installed. -Update the installed python packages with PIP: +Refer to the [invoke installation guide](./start/invoke.md#installation) for more information. -``` -pip3 install -U --require-hashes -r requirements.txt -``` - -### Invoke Version +### Can't find any collection named tasks -If the installed version of invoke is too old, users may see error messages during the installation procedure, such as: +Refer to the [invoke guide](./start/invoke.md#cant-find-any-collection-named-tasks) for more information. -- *'update' did not receive all required positional arguments!* -- *Function has keyword-only arguments or annotations* - -As per the [invoke guide](./start/intro.md#invoke), the minimum required version of Invoke is `{{ config.extra.min_invoke_version }}`. - -To determine the version of invoke you have installed, run either: - -``` -invoke --version -``` -``` -python -m invoke --version -``` - -If you are running an older version of invoke, ensure it is updated to the latest version: +### Invoke Version -``` -pip install -U invoke -``` +If the installed version of invoke is too old, users may see error messages during the installation procedure. Refer to the [invoke guide](./start/invoke.md#minimum-version) for more information. ### No module named 'django' diff --git a/docs/docs/start/accounts.md b/docs/docs/start/accounts.md index 4722f35ebdb..35c53f6453e 100644 --- a/docs/docs/start/accounts.md +++ b/docs/docs/start/accounts.md @@ -17,7 +17,7 @@ This account is created when you first run the InvenTree server instance. The us ### Create Superuser -Another way to create an administrator account is to use the `superuser` command. This will create a new superuser account with the specified username and password. +Another way to create an administrator account is to use the `superuser` command (via [invoke](./invoke.md)). This will create a new superuser account with the specified username and password. ```bash invoke superuser diff --git a/docs/docs/start/intro.md b/docs/docs/start/intro.md index 9b3253aab81..78988461b2b 100644 --- a/docs/docs/start/intro.md +++ b/docs/docs/start/intro.md @@ -70,25 +70,7 @@ InvenTree requires a minimum Python version of {{ config.extra.min_python_versio ### Invoke -InvenTree makes use of the [invoke](https://www.pyinvoke.org/) python toolkit for performing various administrative actions. - -!!! warning "Invoke Version" - InvenTree requires invoke version {{ config.extra.min_invoke_version }} or newer. Some platforms may be shipped with older versions of invoke! - -!!! tip "Updating Invoke" - To update your invoke version, run `pip install -U invoke` - -To display a list of the available InvenTree administration actions, run the following commands from the top level source directory: - -``` -invoke --list -``` - -This provides a list of the available invoke commands - also displayed below: - -``` -{{ invoke_commands() }} -``` +InvenTree makes use of the [invoke](https://www.pyinvoke.org/) python toolkit for performing various administrative actions. You can read [more about out use of the invoke tool here](./invoke.md) ### Virtual Environment diff --git a/docs/docs/start/invoke.md b/docs/docs/start/invoke.md new file mode 100644 index 00000000000..0ec42217246 --- /dev/null +++ b/docs/docs/start/invoke.md @@ -0,0 +1,129 @@ +--- +title: Invoke Tool +--- + +## Invoke Tool + +InvenTree uses the [invoke](https://www.pyinvoke.org/) tool to manage various system administration tasks. Invoke is a powerful python-based task execution tool, which allows for the creation of custom tasks and command-line utilities. + +### Installation + +InvenTree setup and administration requires that the invoke tool is installed. This is usually installed automatically as part of the InvenTree installation process - however (if you are configuring InvenTree from source) you may need to install it manually. + +To install the invoke tool, run the following command: + +``` +pip install -U invoke +``` + +### Minimum Version + +The minimum required version of the invoke tool is `{{ config.extra.min_invoke_version }}`. + +To determine the version of invoke you have installed, run either: + +``` +invoke --version +``` +``` +python -m invoke --version +``` + +If you are running an older version of invoke, ensure it is updated to the latest version: + +``` +pip install -U invoke +``` + +### Running from Command Line + +To run the `invoke` tool from the command line, you must be in the top-level InvenTree source directory. This is the directory that contains the [tasks.py]({{ sourcefile("tasks.py") }}) file. + +### Running in Docker Mode + +If you have installed InvenTree via [docker](./docker_install.md), then you need to ensure that the `invoke` commands are called from within the docker container context. + +For example, to run the `update` task, you might use the following command to run the `invoke` command - using the `docker compose` tool. + +``` +docker compose run --rm inventree-server invoke update +``` + +!!! note "Docker Compose Directory" + The `docker compose` command should be run from the directory where the `docker-compose.yml` file is located. + +Alternatively, to manually run the command within the environment of the running docker container: + +``` +docker exec -it inventree-server invoke update +``` + +!!! note "Container Name" + The container name may be different depending on how you have configured the docker environment. + +### Running in Installer Mode + +If you have installed InvenTree using the [package installer](./installer.md), then you need to prefix all `invoke` commands with `inventree run`. + +For example, to run the `update` task, use: + +``` +inventree run invoke update +``` + +## Available Tasks + +To display a list of the available InvenTree administration actions, run the following commands from the top level source directory: + +``` +invoke --list +``` + +This provides a list of the available invoke commands - also displayed below: + +``` +{{ invoke_commands() }} +``` + +### Task Information + +Each task has a brief description of its purpose, which is displayed when running the `invoke --list` command. To find more detailed information about a specific task, run the command with the `--help` flag. + +For example, to find more information about the `update` task, run: + +``` +invoke update --help +``` + +### Internal Tasks + +Tasks with the `int.` prefix are internal tasks, and are not intended for general use. These are called by other tasks, and should generally not be called directly. + +### Developer Tasks + +Tasks with the `dev.` prefix are tasks intended for InvenTree developers, and are also not intended for general use. + +## Common Issues + +Below are some common issues that users may encounter when using the `invoke` tool, and how to resolve them. + +### Command 'invoke' not found + +If the `invoke` command does not work, it means that the invoke tool has not been [installed correctly](#installation). + +### Invoke Version + +If the installed version of invoke is too old, users may see error messages during the installation procedure, such as: + +- *'update' did not receive all required positional arguments!* +- *Function has keyword-only arguments or annotations* + +Ensure that the installed version of invoke is [up to date](#minimum-version). + +### Can't find any collection named 'tasks' + +It means that the `invoke` tool is not able to locate the InvenTree task collection. + +- If running in docker, ensure that you are running the `invoke` command from within the [docker container](#running-in-docker-mode) +- If running in installer mode, ensure that you are running the `invoke` command with the [correct prefix](#running-in-installer-mode) +- If running via command line, ensure that you are running the `invoke` command from the [correct directory](#running-from-command-line) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 99c49b4dd80..99dd6c9d327 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -100,6 +100,7 @@ nav: - Serving Files: start/serving_files.md - User Accounts: start/accounts.md - Data Backup: start/backup.md + - Invoke: start/invoke.md - Migrating Data: start/migrate.md - Advanced Topics: start/advanced.md - Parts: