Improve devdocs (inventree#4813)

* move devcontainer docs * rename bare metal pages * fix backlinks * Add getting started for devs * add mermaid * include contrib in docs * use another plugin * include everything * update doc checks * fix install command * remove mermaid * remove inclusion tag * remove empty list item * readd include-markdown * use non-conflicting syntax for include * fix table rendering in mkdocs * make controbuting embedable * re-add mermaid * remove empty section * resturcture * remove mermaid again
BarefootBeast · Jun 9, 2023 · 005c834 · 005c834
1 parent 280f624
commit 005c834
Show file tree

Hide file tree

Showing 13 changed files with 56 additions and 20 deletions.
diff --git 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
@@ -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 % }
 
-<span>{% trans "This string will be translated" %} - this string will not!</span>
+<span>{ % trans "This string will be translated" % } - this string will not!</span>
 ```
 
 ## 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
@@ -0,0 +1,3 @@
+{!
+   include-markdown "../../../CONTRIBUTING.md"
+!}
diff --git a/docs/docs/start/devcontainer.md → docs/docs/develop/devcontainer.md b/docs/docs/start/devcontainer.md → docs/docs/develop/devcontainer.md
diff --git a/docs/docs/develop/starting.md 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
@@ -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 → docs/docs/start/bare_dev.md b/docs/docs/start/development.md → docs/docs/start/bare_dev.md
@@ -1,16 +1,16 @@
 ---
-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.
 
 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 → docs/docs/start/bare_prod.md b/docs/docs/start/production.md → 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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