diff --git a/.github/workflows/qc_checks.yaml b/.github/workflows/qc_checks.yaml index f78f502fc9..c89cf7a8f2 100644 --- a/.github/workflows/qc_checks.yaml +++ b/.github/workflows/qc_checks.yaml @@ -99,7 +99,7 @@ jobs: python3 ci/version_check.py mkdocs: - name: Style [documentation] + name: Style [Documentation] runs-on: ubuntu-20.04 needs: paths-filter diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 994f2a4a98..2f6f6599b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -146,7 +146,7 @@ Django are checked by [djlint](https://github.com/Riverside-Healthcare/djlint) t The following rules out of the [default set](https://djlint.com/docs/linter/) are not applied: ```bash -D018: (Django) Internal links should use the {% url ... %} pattern +D018: (Django) Internal links should use the { % url ... % } pattern H006: Img tag should have height and width attributes H008: Attributes should be double quoted H021: Inline styles should be avoided @@ -187,16 +187,16 @@ user_facing_string = _('This string will be exposed to the translation engine!') HTML and javascript files are passed through the django templating engine. Translatable strings are implemented as follows: ```html -{% load i18n %} +{ % load i18n % } -{% trans "This string will be translated" %} - this string will not! +{ % trans "This string will be translated" % } - this string will not! ``` ## Github use ### Tags The tags describe issues and PRs in multiple areas: | Area | Name | Description | -|---|---|---| +| --- | --- | --- | | Triage Labels | | | | | triage:not-checked | Item was not checked by the core team | | | triage:not-approved | Item is not green-light by maintainer | diff --git a/docs/docs/develop/contributing.md b/docs/docs/develop/contributing.md new file mode 100644 index 0000000000..7aad5d3d27 --- /dev/null +++ b/docs/docs/develop/contributing.md @@ -0,0 +1,3 @@ +{! + include-markdown "../../../CONTRIBUTING.md" +!} diff --git a/docs/docs/start/devcontainer.md b/docs/docs/develop/devcontainer.md similarity index 100% rename from docs/docs/start/devcontainer.md rename to docs/docs/develop/devcontainer.md diff --git a/docs/docs/develop/starting.md b/docs/docs/develop/starting.md new file mode 100644 index 0000000000..a47427ba19 --- /dev/null +++ b/docs/docs/develop/starting.md @@ -0,0 +1,27 @@ +--- +title: Getting started +--- + +InvenTree consists of a Django-based backend server, and a HTML / vanilla JS based frontend that uses Bootstrap. The main languages used are Python and Javascript. +As part of the larger project other languages/techniques are used, such as docker (dev/deployment), bash (installer) and markdown (documentation). + +### Getting started +#### Getting to know the basics + +The Django framework is a powerful tool for creating web applications. It is well documented and has a large community. The [Django documentation](https://docs.djangoproject.com/en/stable/) is a good place to start. + +In particular the [tutorial](https://docs.djangoproject.com/en/stable/intro/tutorial01/) is a good way to get to know the basics of Django. +InvenTree follows the best practies for Django so most of the contents should be applicable to InvenTree as well. The REST API is based on the [Django REST framework](https://www.django-rest-framework.org/). + +#### Setting up a development environment + +The recommended way to set up a development environment is to use VSCode devcontainers. The required files are provided with the repo, the docs are on a [dedicated page](./devcontainer.md). + +It is also possible to use [docker development](../start/docker_dev.md) or [bare metal development](../start/bare_dev.md). With these you need to install the required dependencies manually with a dedicated task. +```bash +invoke setup-dev +``` + +#### Following standards + +Before contributing to the project, please read the [contributing guidelines](contributing.md). Pull requests that do not follow the guidelines, do not pass QC checks or lower the test coverage will not be accepted. diff --git a/docs/docs/faq.md b/docs/docs/faq.md index faa600791c..da2b8c4f69 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -98,7 +98,7 @@ invoke worker ``` !!! info "Supervisor" - A better option is to manage the background worker process using a process manager such as supervisor. Refer to the [production server guide](./start/production.md). + A better option is to manage the background worker process using a process manager such as supervisor. Refer to the [production server guide](./start/bare_prod.md). ## Docker Issues diff --git a/docs/docs/start/development.md b/docs/docs/start/bare_dev.md similarity index 88% rename from docs/docs/start/development.md rename to docs/docs/start/bare_dev.md index 3eed337f6d..fdfb02b4cc 100644 --- a/docs/docs/start/development.md +++ b/docs/docs/start/bare_dev.md @@ -1,8 +1,8 @@ --- -title: Development Server +title: Bare Metal Development Server --- -## Development Server +## Bare Metal Development Server !!! warning "Installation" Before continuing, ensure that the [installation steps](./install.md) have been completed. @@ -10,7 +10,7 @@ title: Development Server InvenTree includes a simple server application, suitable for use in a development environment. !!! warning "Deployment" - Refer to the [production server instructions](./production.md) to implement a much more robust server setup. + Refer to the [production server instructions](./bare_prod.md) to implement a much more robust server setup. ### Running on a Local Machine diff --git a/docs/docs/start/production.md b/docs/docs/start/bare_prod.md similarity index 98% rename from docs/docs/start/production.md rename to docs/docs/start/bare_prod.md index 192bac461b..de70572898 100644 --- a/docs/docs/start/production.md +++ b/docs/docs/start/bare_prod.md @@ -1,8 +1,8 @@ --- -title: Production Server +title: Bare Metal Production Server --- -## Production Server +## Bare Metal Production Server !!! warning "Installation" Before continuing, ensure that the [installation steps](./install.md) have been completed. diff --git a/docs/docs/start/install.md b/docs/docs/start/install.md index e4d659cddd..1d379560a6 100644 --- a/docs/docs/start/install.md +++ b/docs/docs/start/install.md @@ -259,13 +259,13 @@ The InvenTree database is now setup and ready to run. A simple development serve The InvenTree development server is useful for testing and configuration - and it may be wholly sufficient for a small-scale installation. -Refer to the [development server instructions](./development.md) for further information. +Refer to the [development server instructions](./bare_dev.md) for further information. ### Production Server In a production environment, a more robust server setup is required. -Refer to the [production server instructions](./production.md) for further information. +Refer to the [production server instructions](./bare_prod.md) for further information. ## Updating InvenTree diff --git a/docs/docs/start/intro.md b/docs/docs/start/intro.md index 51c30ea610..6286322fa6 100644 --- a/docs/docs/start/intro.md +++ b/docs/docs/start/intro.md @@ -38,7 +38,7 @@ The bulk of the InvenTree code base supports the custom web server application. The webserver code also provides a first-party API for performing database query actions. -Once a database is setup, you need a way of accessing the data. InvenTree provides a "server" application out of the box, but this may not scale particularly well with multiple users. Instead, InvenTree can be served using a webserver such as [Gunicorn](https://gunicorn.org/). For more information see the [deployment documentation](./production.md). +Once a database is setup, you need a way of accessing the data. InvenTree provides a "server" application out of the box, but this may not scale particularly well with multiple users. Instead, InvenTree can be served using a webserver such as [Gunicorn](https://gunicorn.org/). For more information see the [deployment documentation](./bare_prod.md). ### Background Tasks @@ -143,7 +143,7 @@ If you do not wish to use the docker container, you will need to manually instal Refer to the following guides for further instructions: -- [**Bare metal development server setup guide**](./development.md) +- [**Bare metal development server setup guide**](./bare_dev.md) - [**Bare metal production server setup guide**](./install.md) ## Debug Mode diff --git a/docs/docs/start/serving_files.md b/docs/docs/start/serving_files.md index c73ff3ead9..0d9b5a493a 100644 --- a/docs/docs/start/serving_files.md +++ b/docs/docs/start/serving_files.md @@ -6,7 +6,7 @@ title: Serving Static and Media Files In production, the InvenTree web server software *does not* provide hosting of static files, or user-uploaded (media) files. -When running in [production mode](./production.md) (i.e. the `INVENTREE_DEBUG` flag is disabled), a separate web server is required for serving *static* and *media* files. In `DEBUG` mode, the django webserver facilitates delivery of *static* and *media* files, but this is explicitly not suitable for a production environment. +When running in [production mode](./bare_prod.md) (i.e. the `INVENTREE_DEBUG` flag is disabled), a separate web server is required for serving *static* and *media* files. In `DEBUG` mode, the django webserver facilitates delivery of *static* and *media* files, but this is explicitly not suitable for a production environment. !!! into "Read More" You can find further information in the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/deployment/). diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 6d4bed838f..ac3361b7bd 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -75,6 +75,10 @@ nav: - Credits: credits.md - Privacy: privacy.md - Terminology: terminology.md + - Development: + - Getting started: develop/starting.md + - Contributing: develop/contributing.md + - Devcontainer: develop/devcontainer.md - Install: - Introduction: start/intro.md - Configuration: start/config.md @@ -85,10 +89,8 @@ nav: - Bare Metal: - Introduction: start/install.md - Installer: start/installer.md - - Production: start/production.md - - Development: start/development.md - - Development: - - Devcontainer: start/devcontainer.md + - Production: start/bare_prod.md + - Development: start/bare_dev.md - Serving Files: start/serving_files.md - Data Backup: start/backup.md - Migrating Data: start/migrate.md @@ -207,6 +209,9 @@ nav: # Plugins plugins: + - include-markdown: + opening_tag: "{!" + closing_tag: "!}" - search - git-revision-date-localized - mkdocs-simple-hooks: diff --git a/docs/requirements.txt b/docs/requirements.txt index b403dd2196..569638391e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,3 +2,4 @@ mkdocs-macros-plugin>=0.7,<1.0 mkdocs-material>=9.0,<10.0 mkdocs-git-revision-date-localized-plugin>=1.1,<2.0 mkdocs-simple-hooks>=0.1,<1.0 +mkdocs-include-markdown-plugin