Improved documentation

docs/_config.yaml

@@ -11,7 +11,8 @@ baseurl: "/" # the subpath of your site, e.g. /blog
 favicon_ico: "/assets/favicon.ico"
 
 aux_links:
-  Part-DB Repository: https://github.com/Part-DB/Part-DB-symfony
+  Part-DB Repository: https://github.com/Part-DB/Part-DB-server
+  Demo: https://part-db.herokuapp.com
 
 
 search_enabled: true
@@ -25,7 +26,7 @@ back_to_top_text: "Back to top"
 # Footer "Edit this page on GitHub" link text
 gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub."
-gh_edit_repository: "https://github.com/Part-DB/Part-DB-symfony" # the github URL for your repo
+gh_edit_repository: "https://github.com/Part-DB/Part-DB-server" # the github URL for your repo
 gh_edit_branch: "master" # the branch that your docs is served from
 gh_edit_source: docs # the source that your files originate from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately

docs/concepts.md

@@ -5,7 +5,10 @@ nav_order: 2
 ---
 
 # Concepts
-This page explains the different concepts of Part-DB and what their intended use is
+This page explains the different concepts of Part-DB and what their intended use is:
+
+1. TOC
+{:toc}
 
 ## Part managment
 

docs/configuration.md

@@ -54,3 +54,26 @@ If you wanna use want to revert changes or view older revisions of entities, the
 * `FIXER_API_KEY`: If you want to automatically retrieve exchange rates for base currencies other than euros, you have configure an exchange rate provider API. [Fixer.io](https://fixer.io/) is preconfigured, and you just have to register there and set the retrieved API key in this environment variable.
 * `APP_ENV`: This value should always be set to `prod` in normal use. Set it to `dev` to enable debug/development mode. (**You should not do this on a publicly accessible server, as it will leak sensitive informations!**)
 * `BANNER`: You can configure the text that should be shown as the banner on the homepage. Useful especially for docker container. In all other applications you can just change the `config/banner.md` file.
+
+## Banner
+To change the banner you can find on the homepage, you can either set the `BANNER` environment variable to the text you
+want to show, or you can edit the `config/banner.md` file. The banner is written in markdown, so you can use all
+markdown (and even some subset of HTML) syntax to format the text.
+
+## parameters.yaml
+You can also configure some options via the `config/parameters.yaml` file. This should normally not needed, 
+and you should know what you are doing, when you change something here. You should expect, that you will have to do some 
+manual merge, when you have changed something here and update to a newer version of Part-DB. It is possible that configuration
+options here will change or completely removed in future versions of Part-DB.
+
+If you change something here, you have to clear the cache, before the changes will take effect with the command `bin/console cache:clear`.
+
+The following options are available:
+
+* `partdb.global_theme`: The default theme to use, when no user specific theme is set. Should be one of the themes from the `partdb.available_themes` config option.
+* `partdb.locale_menu`: The codes of the languages, which should be shown in the language chooser menu (the one with the user icon in the navbar). The first language in the list will be the default language.
+* `partdb.gpdr_compliance`: When set to true (default value), IP addresses which are saved in the database will be anonymized, by removing the last byte of the IP. This is required by the GDPR (General Data Protection Regulation) in the EU.
+* `partdb.sidebar.items`: The panel contents which should be shown in the sidebar by default. You can also change the number of sidebar panels by changing the number of items in this list.
+* `partdb.sidebar.root_node_enable`: Show a root node in the sidebar trees, of which all nodes are children of
+* `partdb.sidebar.root_expanded`: Expand the root node in the sidebar trees by default
+* `partdb.available_themes`: The list of available themes a user can choose from.

docs/index.md

@@ -56,7 +56,7 @@ There you will find various methods to support development on a monthly or a one
 ## Built with
 * [Symfony 5](https://symfony.com/): The main framework used for the serverside PHP
 * [Bootstrap 5](https://getbootstrap.com/) and [Bootswatch](https://bootswatch.com/): Used as website theme
-* [Fontawesome](https://fontawesome.com/: Used as icon set
+* [Fontawesome](https://fontawesome.com/): Used as icon set
 * [Hotwire Stimulus](https://stimulus.hotwired.dev/) and [Hotwire Turbo](https://turbo.hotwired.dev/): Frontend Javascript
 
 ## Authors

docs/installation/installation_docker.md

@@ -68,12 +68,12 @@ services:
       # When this is empty the content of config/banner.md is used as banner
       #- BANNER=This is a test banner<br>with a line break
 ```
-
-4. Inside the folder, run
+4. Customize the settings by changing the environment variables (or add new ones). See [Configuration]({% link configuration.md %}) for more information.
+5. Inside the folder, run
 ```bash
    docker-compose up -d
 ```    
-5. Create the inital database with 
+6. Create the inital database with 
  ```bash
 docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate
  ```

docs/installation/installation_guide-debian.md

@@ -90,7 +90,7 @@ The basic configuration of Part-DB is done by a `.env.local` file in the main di
 cp .env .env.local
 ```
 
-In your `.env.local` you can configure Part-DB according to your wishes. A full list of configuration options can be found **TODO**.
+In your `.env.local` you can configure Part-DB according to your wishes. A full list of configuration options can be found [here]({% link configuration.md %}.
 Other configuration options like the default language or default currency can be found in `config/parameters.yaml`.
 
 Please check that the `partdb.default_currency` value in `config/parameters.yaml` matches your mainly used currency, as this can not be changed after creating price informations.

docs/usage/getting_started.md

@@ -7,54 +7,50 @@ nav_order: 4
 # Getting started
 
 After Part-DB you should begin with customizing the settings, and setting up the basic structures.
-Before starting its useful to read a bit about the [concepts of Part-DB](https://github.com/Part-DB/Part-DB-symfony/wiki/Concepts).
+Before starting its useful to read a bit about the [concepts of Part-DB]({% link concepts.md %}).
+
+1. TOC
+{:toc}
 
 ## Customize config files
 
-<details>
-<summary>Click to expand</summary>
-
 Before you start creating data structures, you should configure Part-DB to your needs by changing possible configuration options.
 This is done either via changing the `.env.local` file in a direct installation or by changing the env variables in your `docker-compose.yaml` file.
-A list of possible configuration options, can be found [here](Configuration).
-
-</details>
+A list of possible configuration options, can be found [here]({% link configuration.md %}).
 
 ## Change password, Set up Two-Factor-Authentication & Customize User settings
 
-<details>
-<summary>Click to expand</summary>
-
 If you have not already done, you should change your user password. You can do this in the user settings (available in the navigation bar drop down with the user symbol).
 
-![image](https://user-images.githubusercontent.com/5410681/190141016-5539a125-3215-48bb-b61b-7c646c352d4d.png)
+![image]({% link assets/getting_started/change_password.png %})
 
 There you can also find the option, to set up Two Factor Authentication methods like Google Authenticator. Using this is highly recommended (especially if you have admin permissions) to increase the security of your account. (Two Factor Authentication even can be enforced for all members of a user group)
 
 In the user settings panel you can change account infos like your username, your first and last name (which will be shown alongside your username to identify you better), department information and your email address. The email address is used to send password reset mails, if your system is configured to use this.
 
-![image](https://user-images.githubusercontent.com/5410681/190142624-0b4d4153-33ea-46e6-baba-5723b5ba9f52.png)
+![image]({% link assets/getting_started/user_settings.png %})
 
 In the configuration tab you can also override global settings, like your preferred UI language (which will automatically be applied after login), the timezone you are in (and in which times will be shown for you), your preferred currency (all money values will be shown converted to this to you, if possible) and the theme that should be used.
-</details>
+
+## (Optional) Customize homepage banner
+
+The banner which is shown on the homepage, can be customized/changed by changing the `config/banner.md` file with a text editor. You can use markdown and (safe) HTML here, to style and customize the banner.
+You can even use Latex style equations by wrapping the expressions into `$` (like `$E=mc^2$`, which is rendered inline: $E=mc^2$) or `$$` (like `$$E=mc^2$$`) which will be rendered as a block, like so: $$E=mc^2$$
 
 ## Create groups, users and customize permissions
 
-<details>
-<summary>Click to expand</summary>
-
 ### Users
 
 When logged in as administrator, you can open the users menu in the `Tools` section of the sidebar under `System -> Users`.
 At this page you can create new users, change their passwords and settings and change their permissions.
 For each user which should use Part-DB you should setup a own account, so that tracking of what user did what works properly.
-![image](https://user-images.githubusercontent.com/5410681/193269065-cf0695b9-21bd-4697-87ab-1557197ef0f6.png)
+![image]({% link assets/getting_started/user_admin.png %})
 
 
 You should check the permissions for every user and ensure that they are in the intended way, and no user has more permissions than he needs.
 For each capability you can choose between allow, forbid and inherit. In the last case, the permission is determined by the group a user has (if no group is chosen, it equals forbid)
 
-![image](https://user-images.githubusercontent.com/5410681/193269185-3a783628-44ca-4dcf-9629-fc6af2e39709.png)
+![image]({% link assets/getting_started/user_permissions.png %})
 
 
 ### Anonymous user
@@ -75,18 +71,14 @@ Users only use the setting of a capability from a group, if the user has a group
 Groups are organized as trees, meaning a group can have parent and child permissions and child groups can inherit permissions from their parents.
 To inherit the permissions from a parent group set the capability to inherit, otherwise set it explicitly to override the parents permission.
 
-</details>
 
 ## Create Attachment types
 
-<details>
-<summary>Click to expand</summary>
-
 Every attachment (that is an file associated with a part, data structure, etc.) must have an attachment type. They can be used to group attachments logically, like differentiating between datasheets, pictures and other documents.
 
 You can create/edit attachment types in the tools sidebar under "Edit -> Attachment types":
 
-![image](https://user-images.githubusercontent.com/5410681/206695965-60a15725-c690-456c-bbdb-d6af858ee75b.png)
+![image]({% link assets/getting_started/attachment_type_admin.png %})
  
 Depending on your usecase different entries here make sense. For part mananagment the following (additional) entries maybe make sense:
 
@@ -95,42 +87,77 @@ Depending on your usecase different entries here make sense. For part mananagmen
 
 For every attachment type a list of allowed file types, which can be uploaded to an attachment with this attachment type, can be defined. You can either pass a list of allowed file extensions (e.g. `.pdf, .zip, .docx`) and/or a list of [Mime Types](https://en.wikipedia.org/wiki/Media_type) (e.g. `application/pdf, image/jpeg`) or a combination of both here. To allow all browser supported images, you can use `image/*` wildcard here.
 
-</details>
-
 ## (Optional) Create Currencies
 
-<details>
-<summary>Click to expand</summary>
 If you want to save priceinformations for parts in a currency different to your global currency (by default Euro), you have to define the additional currencies you want to use under `Edit -> Currencies`:
 
-![image](https://user-images.githubusercontent.com/5410681/206698733-01e22c0b-c871-438a-a98d-f09f1c03fe90.png)
+![image]({% link assets/getting_started/currencies_admin.png %})
 
 You create a new currency, name it however you want (it is recommended to use the official name of the currency) and select the currency ISO code from the list and save it. The currency symbol is determined automatically from chose ISO code.
 You can define a exchange rate in terms of your base currency (e.g. how much euros is one unit of your currency worth) to convert the currencies values in your preferred display currency automatically. 
 
 
-</details>
-
 ## (Optional) Create Measurement Units
 
-<details>
-<summary>Click to expand</summary>
-
-By default Part-DB assumes that the parts in inventory can be counted by individual indivisible pieces, like LEDs in a box or books in a shelf. However if you want to manage things, that are divisible and and the instock is described by a physical quantity, like length for cables, or volumina of a liquid, you have to define additional measurement units.
+By default Part-DB assumes that the parts in inventory can be counted by individual indivisible pieces, like LEDs in a box or books in a shelf. 
+However if you want to manage things, that are divisible and and the instock is described by a physical quantity, like length for cables, or volumina of a liquid, you have to define additional measurement units.
 
 This is possible under `Edit -> Measurement Units`:
-![image](https://user-images.githubusercontent.com/5410681/206701450-40a5f323-21ea-4889-a68b-8fb6c3d2f46d.png)
+![image]({% link assets/getting_started/units_admin.png %})
 
 You can give the measurement unit a name and an optional unit symbol (like `m` for meters) which is shown when quantities in this unit are displayed. The option `Use SI prefix` is useful for almost all physical quantities, as big and small numbers are automatically formatted with SI-prefixes (like 1.5kg instead 1500 grams).
 
 The measurement unit can be selected for each part individually, by setting the option in the advanced tab of a part`s edit menu.
 
-</details>
+## Create Categories
 
-## (Optional) Customize homepage banner
+A category is used to group parts logically by their function (e.g. all NPN transistors would be put in a "NPN-Transistors" category). 
+Categories are hierarchical structures meaning that you can create logical trees to group categories together.
+See [Concepts]({% link concepts.md %}) for an example tree structure.
 
-<details>
-<summary>Click to expand</summary>
-The banner which is shown on the homepage, can be customized/changed by changing the `config/banner.md` file with a text editor. You can use markdown and (safe) HTML here, to style and customize the banner.
-You can even use Latex style equations by wrapping the expressions into `$` (like `$E=mc^2$`, which is rendered inline: $E=mc^2$) or `$$` (like `$$E=mc^2$$`) which will be rendered as a block, like so: $$E=mc^2$$
-</details>
+Creating/Editing categories is done in the tools sidebar under "Edit -> Categories".
+
+Every part has to be assigned to a category, so you should create at least one category before you start adding parts.
+
+## (Optional) Create Footprints
+
+Footprints are used to describe the physical shape of a part, like a resistor or a capacitor. 
+They can be used to group parts by their physical shape and to find parts with in the same package.
+
+You can create/edit footprints in the tools sidebar under "Edit -> Footprints".
+
+It is useful to create footprints for the most common packages, like SMD resistors, capacitors, etc. to make it easier to find parts with the same footprint.
+You should create these as a tree structure, so that you can group footprints by their type.
+See [Concepts]({% link concepts.md %}) for an example tree structure.
+
+You can define attachments here which are associated with the footprint. The attachment set as preview image, will be
+used whenever a visual representation of the footprint is needed (e.g. in the part list).
+
+For many common footprints, you can use the built-in footprints, which can be found in the "Builtin footprint image gallery", which you can find in the tools menu.
+Type the name of the image you want to use in the URL field of the attachment and select the image from the dropdown menu.
+
+## (Optional) Create Storage locations
+
+A storelocation represents a place where parts can be stored.
+
+You can create/edit storage locations in the tools sidebar under "Edit -> Storage locations".
+
+## (Optional) Create Manufacturers and suppliers
+
+You can create/edit [manufacturers]({% link concepts.md %}#manufacturers) and [suppliers]({% link concepts.md %}#suppliers) in the tools sidebar under "Edit -> Manufacturers" and "Edit -> Suppliers".
+
+## Create parts
+
+You are now ready to create your first part. You can do this by clicking either by clicking "Edit -> New Part" in the tools sidebar tree
+or by clicking the "Create new Part" above the (empty) part list, after clicking on one of your newly created categories.
+
+You will be presented with a form where you can enter the basic information about your part:
+
+![image]({% link assets/getting_started/new_part.png %})
+
+You have to enter at least a name for the part and choose a category for it, the other fields are optional.
+However, it is recommended to fill out as much information as possible, as this will make it easier to find the part later.
+
+You can choose from your created datastructures to add manufacturer information, supplier information, etc. to the part.
+You can also create new datastructures on the fly, if you want to add additional information to the part, by typing the
+name of the new datastructure in the field and select the "New ..." option in the dropdown menu. See [tips]({% link usage/tips_tricks.md %}) for more information.

docs/usage/labels.md

@@ -85,11 +85,11 @@ You can use the "Placeholders" dropdown in content editor, to automatically inse
 
 If you select "Twig" in parser mode under advanced settings, you can input a twig template in the lines field (activate source mode). You can use most of the twig tags and filters listed in [offical documentation](https://twig.symfony.com/doc/3.x/).
 
-The following variables are in injected into Twig and can be accessed using `{{ variable }}` (or `{{ variable.property }}`):
+The following variables are in injected into Twig and can be accessed using `{% raw %}{{ variable }}` (or `{% raw %}{{ variable.property }}{% endraw %}`):
 
-| Variable name | Description |
-| ------------- | ----------- |
-| `{{ element }}` | The target element, selected in label dialog |
-| `{{ user }}`   | The current logged in user. Null if you are not logged in |
-| `{{ install_title }}` | The name of the current Part-DB instance (similar to [[INSTALL_NAME]] placeholder). |
-| `{{ page }}` | The page number (the nth-element for which the label is generated |
+| Variable name                        | Description |
+|--------------------------------------| ----------- |
+| `{% raw %}{{ element }}{% endraw %}` | The target element, selected in label dialog |
+| `{% raw %}{{ user }}{% endraw %}`                         | The current logged in user. Null if you are not logged in |
+| `{% raw %}{{ install_title }}{% endraw %}`                | The name of the current Part-DB instance (similar to [[INSTALL_NAME]] placeholder). |
+| `{% raw %}{{ page }}{% endraw %}`                         | The page number (the nth-element for which the label is generated |

docs/usage/tips_tricks.md

@@ -0,0 +1,65 @@
+---
+title: Tips & Tricks
+layout: default
+parent: Usage
+---
+
+# Tips & Tricks
+
+Following you can find miscellaneous tips and tricks for using Part-DB.
+
+## Create datastructures directly from part edit page
+
+Instead of first creating a category, manufacturer, footprint, etc. and then creating the part, you can create the 
+datastructures directly from the part edit page: Just type the name of the datastructure you want to create into the 
+select field on the part edit page and press "Create new ...". The new datastructure will be created, when you save
+the part changes.
+
+You can create also create nested datastructures this way. For example, if you want to create a new category "AVRs", 
+as a subcategory of "MCUs", you can just type "MCUs->AVRs" into the category select field and press "Create new".
+The new category "AVRs" will be created as a subcategory of "MCUs". If the category "MCUs" does not exist, it will
+be created too.
+
+## Builtin footprint images
+Part-DB includes several builtin images for common footprints. You can use these images in your footprint datastructures,
+by creating an attachment on the datastructure and selecting it as preview image.
+Type the name of the footprint image you want to use into the URL field of the attachment and select it from the
+dropdown menu. You can find a gallery of all builtin footprint images and their names in the "Builtin footprint image gallery",
+which you can find in the "Tools" menu (you maybe need to give your user the permission to access this tool).
+
+## Parametric search
+In the "parameters" tab of the filter panel on parts list page, you can define constraints, which parameter values
+have to fullfill. This allows you to search for parts with specific parameters (or parameter ranges), for example you
+can search for all parts with a voltage rating of greater than 5 V.
+
+## View own users permissions
+If you want to see which permissions your user has, you can find a list of the permissions in the "Permissions" panel
+on the user info page.
+
+## Use LaTeX equations
+You can use LaTeX equations everywhere where markdown is supported (for example in the description or notes field of a part).
+[KaTeX](https://katex.org/) is used to render the equations.
+You can find a list of supported features in the [KaTeX documentation](https://katex.org/docs/supported.html).
+
+To input a LaTeX equation, you have to wrap it in a pair of dollar signs (`$`). Single dollar signs mark inline equations,
+double dollar signs mark displayed equations (which will be its own line and centered). For example, the following equation
+will be rendered as an inline equation:
+
+```
+$E=mc^2$
+```
+
+while this one will be rendered as a displayed equation:
+
+```
+$$E=mc^2$$
+```
+
+## Update currency exchange rates automatically
+Part-DB can update the currency exchange rates of all defined currencies programatically
+by calling the `php bin/console partdb:currencies:update-exchange-rates`.
+
+If you call this command regularly (e.g. with a cronjob), you can keep the exchange rates up-to-date.
+
+Please note that if you use a base currency, which is not the Euro, you have to configure an exchange rate API, as the
+free API used by default only supports the Euro as base currency.