From b974e5f3fa94d2049b5d9c8ebda2fd45ac30dd5d Mon Sep 17 00:00:00 2001 From: Mitch Davis Date: Thu, 18 Dec 2025 15:19:06 +1100 Subject: [PATCH 1/5] Improvements to the documentation instructions --- docs/README.md | 38 +++++++++++--------------------------- 1 file changed, 11 insertions(+), 27 deletions(-) diff --git a/docs/README.md b/docs/README.md index 5d51b82029a9..017cc6bd53b2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -38,19 +38,13 @@ $ cd src $ pip install --require-hashes -r docs/requirements.txt ``` -## Build Documentation +## Schema generation -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 -``` +Building the documentation requires extracting the API schema from the source code. !!! tip 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 - ``` $ invoke build-docs ``` @@ -71,41 +65,31 @@ 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 +## Viewing the documentation -To view the documentation locally, run the following command to start the MkDocs webpage server: +Generate the HTML files from the markdown source files, and start the MkDocs webpage server: ``` -$ mkdocs serve -f docs/mkdocs.yml -a localhost:8080 +$ mkdocs serve -f docs/mkdocs.yml ``` -Alternatively, you can use the `invoke` command: - -``` -invoke dev.docs-server -``` +You can then point your web browser at http://localhost:8080/ -To see all the available options: +Alternatively, you can use the `invoke` command: ``` -invoke dev.docs-server --help +$ invoke dev.docs-server ``` -You can then point your web browser at http://localhost:8080/ +If you need to, use the `-a` option after `mkdocs` or `invoke` to set the address and port. Run `invoke dev.docs-server --help` for details. ## Editing the Documentation Files -Once the server is running, it will monitor the documentation files for any changes, and regenerate the HTML pages. +Once the server is running, it will monitor the documentation files for changes, and regenerate the HTML pages as required. Refresh your web browser to see the changes. ### Admonitions -"Admonition" blocks can be added as follow: +"Admonition" blocks can be added to the documentation source as follows: ``` !!! info "This is the admonition block title" This is the admonition block content From ae58839efd1ded8b40ea1f99a1ffb8443191009a Mon Sep 17 00:00:00 2001 From: Mitch Davis Date: Fri, 19 Dec 2025 12:24:41 +1100 Subject: [PATCH 2/5] Move README.md file into docs/ subdir so mkdocs can see it --- docs/{README.md => docs/documentation-howto.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{README.md => docs/documentation-howto.md} (100%) diff --git a/docs/README.md b/docs/docs/documentation-howto.md similarity index 100% rename from docs/README.md rename to docs/docs/documentation-howto.md From d9a5334656c2dbc57083e5034f61726496fb1365 Mon Sep 17 00:00:00 2001 From: Mitch Davis Date: Fri, 19 Dec 2025 12:28:58 +1100 Subject: [PATCH 3/5] Linked old README.md into mkdocs and dded a redirection from top level. --- docs/README.md | 5 +++++ docs/docs/documentation-howto.md | 4 ++++ docs/mkdocs.yml | 1 + 3 files changed, 10 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000000..78237f37b389 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,5 @@ +# InvenTree Documentation + +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. + +For instructions on writing Markdown, and generating and viewing the documentation locally, see the [docs/documentation-howto.md](./docs/documentation-howto.md). diff --git a/docs/docs/documentation-howto.md b/docs/docs/documentation-howto.md index 017cc6bd53b2..2551477a81b7 100644 --- a/docs/docs/documentation-howto.md +++ b/docs/docs/documentation-howto.md @@ -122,7 +122,9 @@ Click [here](/part/views) Images are served from the `./docs/assets/images` folder and can be added as follows: ``` +{% raw %} {{ image("image_name.png", base="subfolder", title="Image title") }} +{% endraw %} ``` See the `image` macro in `./docs/main.py` for more information. @@ -132,7 +134,9 @@ See the `image` macro in `./docs/main.py` for more information. Icons can be rendered (using the [tabler icon set](https://tabler.io/icons)) as follows: ``` +{% raw %} {{ icon("brand-github", color="red")}} +{% endraw %} ``` See the `icon` macro in `./docs/main.py` for more information. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index d9585f3996dc..b6aa7fd3329c 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -79,6 +79,7 @@ nav: - Release Notes: releases/release_notes.md - Development: - InvenTree Development: develop/index.md + - Documentation: documentation-howto.md - Contributing: develop/contributing.md - Architecture: develop/architecture.md - Roadmap: develop/roadmap.md From 9d0984a5f50839cceb892fe5798f4badc7bd9fab Mon Sep 17 00:00:00 2001 From: Mitch Davis Date: Sat, 20 Dec 2025 00:21:36 +1100 Subject: [PATCH 4/5] Moving this file broke links to peer pages. Fixed. --- docs/docs/documentation-howto.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/docs/documentation-howto.md b/docs/docs/documentation-howto.md index 2551477a81b7..d0dfa73fdf96 100644 --- a/docs/docs/documentation-howto.md +++ b/docs/docs/documentation-howto.md @@ -14,7 +14,7 @@ InvenTree uses [MkDocs](https://www.mkdocs.org/) to convert [Markdown](https://w * 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. + These instructions assume you followed the [InvenTree bare metal installation instructions](./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. @@ -109,14 +109,12 @@ For example, to link to the page `/part/views` from `/stock/stocktake`, the link Click [here](../part/views.md) ``` -*Formatting the link as follows:* +*The following format will result in a broken link.* ``` Click [here](/part/views) ``` -*will result in a broken link.* - ### Images Images are served from the `./docs/assets/images` folder and can be added as follows: From d0ad2e1ad4b46eccf28c8d67d1f33e98858d694f Mon Sep 17 00:00:00 2001 From: Mitch Davis Date: Sat, 20 Dec 2025 00:36:56 +1100 Subject: [PATCH 5/5] Tell the doc link checker to allow this example link --- docs/mlc_config.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/mlc_config.json b/docs/mlc_config.json index a3e538ca10d0..357d765ecead 100644 --- a/docs/mlc_config.json +++ b/docs/mlc_config.json @@ -34,6 +34,9 @@ }, { "pattern": "^https://dev.azure.com" + }, + { + "pattern": "^https://itree.example.com/itree-admin/" } ] }