inventree/InvenTree
2
0
Fork 0
mirror of https://github.com/inventree/InvenTree.git synced 2025-12-17 09:48:30 +00:00
Code Activity

Improve the documentation installation instructions. (#11011)

Browse Source 
Co-authored-by: Mitch Davis <mjd@afork.com>
This commit is contained in:
Mitch Davis
2025-12-14 21:26:06 +11:00
committed by GitHub
parent 0460e81f9a
commit a727c4e2f9
1 changed files with 63 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/README.md
View File

@@ -4,32 +4,82 @@
This repository hosts the [official documentation](https://inventree.readthedocs.io/) for [InvenTree](https://github.com/inventree/inventree), an open source inventory management system.
To serve this documentation locally (e.g. for development), you will need to have Python 3 installed on your system.
## Prerequisites
## Setup
InvenTree uses [MkDocs](https://www.mkdocs.org/) to convert [Markdown](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown) format `.md` files into HTML suitable for viewing in a web browser.
Run the following commands from the top-level project directory:
!!! info "Prerequisites"
To build and serve this documentation locally (e.g. for development), you will need:
* Python 3 installed on your system.
* An existing InvenTree installation containing the virtual environment that was created during installation.
These instructions assume you followed the [InvenTree bare metal installation instructions](./docs/start/install.md), so you'll have an `inventree` user, a home directory at `/home/inventree`, the InvenTree source code cloned from [GitHub](https://github.com/inventree/inventree) into `/home/inventree/src`, and a virtual environment at `/home/inventree/env`. If you installed InvenTree some other way, this might vary, and you'll have to adjust these instructions accordingly.
!!! warning "Your InvenTree install will be updated!"
Some of the commands that follow will make changes to your install, for example, by running any pending database migrations. There's a small risk this may cause issues with your existing installation. If you can't risk this, consider setting up a separate InvenTree installation specifically for documentation development.
## Building the documentation locally
To build the documentation locally, run these commands as the `inventree` user:
```
$ git clone https://github.com/inventree/inventree
$ cd /home/inventree
$ source env/bin/activate
```
!!! info "(env) prefix"
The shell prompt should now display the `(env)` prefix, showing that you are operating within the context of the python virtual environment
You can now install the additional packages needed by mkdocs:
```
$ cd src
$ pip install --require-hashes -r docs/requirements.txt
```
## Build Documentation
Before serving the documentation, you will need to build the documentation files:
Before serving the documentation, you will need to build the API schema files from the source code, so they can be included in the documentation:
```
invoke build-docs
```
This is required to generate the required API schema files, and must be run before the documentation can be served.
!!! tip
This command is only required when building the documentation for the first time, or when changes have been made to the API schema.
Note that this command is only required when building the documentation for the first time, or when changes have been made to the API schema.
## Serve Local files
## Serve Locally
```
$ invoke build-docs
```
To serve the pages locally, run the following command (from the top-level project directory):
You will see output similar to this (truncated for brevity):
```
Running InvenTree database migrations...
Exporting definitions...
Exporting settings definition to '/home/inventree/src/docs/generated/inventree_settings.json'...
Exported InvenTree settings definitions to '/home/inventree/src/docs/generated/inventree_settings.json'
Exported InvenTree tag definitions to '/home/inventree/src/docs/generated/inventree_tags.yml'
Exported InvenTree filter definitions to '/home/inventree/src/docs/generated/inventree_filters.yml'
Exported InvenTree report context definitions to '/home/inventree/src/docs/generated/inventree_report_context.json'
Exporting definitions complete
Exporting schema file to '/home/inventree/src/docs/generated/schema.yml'
Schema export completed: /home/inventree/src/docs/generated/schema.yml
Documentation build complete, but mkdocs not requested
```
If that worked, you can now generate the HTML format documentation pages:
```
$ mkdocs build -f docs/mkdocs.yml
```
## Viewing the generated output
To view the documentation locally, run the following command to start the MkDocs webpage server:
```
$ mkdocs serve -f docs/mkdocs.yml -a localhost:8080
@@ -47,9 +97,11 @@ To see all the available options:
invoke dev.docs-server --help
```
## Edit Documentation Files
You can then point your web browser at http://localhost:8080/
Once the server is running, it will monitor the documentation files for any changes, and update the served pages.
## Editing the Documentation Files
Once the server is running, it will monitor the documentation files for any changes, and regenerate the HTML pages.
### Admonitions