Improved documentation

docs/.gitignore

@@ -0,0 +1,5 @@
+.jekyll-cache/
+_site/
+
+Gemfile.lock
+.bundles_cache

docs/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+# do NOT include the Jekyll gem !
+#gem 'github-pages', group: :jekyll_plugins
+gem "kramdown-parser-gfm"
+gem "just-the-docs"
+gem "jekyll"
+gem 'jekyll-seo-tag'

docs/_config.yaml

@@ -1,20 +1,48 @@
 title: Part-DB
-description: A starter template for a Jeykll site using the Just the Docs theme!
+description: Open source inventory management system for your electronic components.
 remote_theme: just-the-docs/just-the-docs
 
 url: "https://part-db.github.io"
 baseurl: "/Part-DB-symfony" # 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
 
 
 search_enabled: true
 
+enable_copy_code_button: true
+heading_anchors: true
+
+back_to_top: true
+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_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
+gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
+
+callouts_level: quiet # or loud
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
+plugins:
+  - jekyll-seo-tag

docs/_config_dev.yaml

@@ -0,0 +1,2 @@
+url: http://localhost:4000
+theme: just-the-docs

docs/index.md

@@ -5,18 +5,20 @@ nav_order: 0
 ---
 
 # Part-DB
-Part-DB is an Open-Source inventory managment system for your electronic components.
+Part-DB is an Open-Source inventory management system for your electronic components.
 It is installed on a web server and so can be accessed with any browser without the need to install additional software.
 
-## Demo
+{: .important-title }
-If you want to test Part-DB without installing it, you can use [this](https://part-db.herokuapp.com) Heroku instance. 
+> Demo
-(Or this link for the [German Version](https://part-db.herokuapp.com/de/)). 
+> 
-
+> If you want to test Part-DB without installing it, you can use [this](https://part-db.herokuapp.com) Heroku instance. 
-You can log in with username: *user* and password: *user*.
+> (Or this link for the [German Version](https://part-db.herokuapp.com/de/)). 
-
+>
-Every change to the master branch gets automatically deployed, so it represents the currenct development progress and is
+> You can log in with username: **user** and password: **user**, to change/create data.
-maybe not completly stable. Please mind, that the free Heroku instance is used, so it can take some time when loading the page
+>
-for the first time.
+> Every change to the master branch gets automatically deployed, so it represents the currenct development progress and is
+> maybe not completly stable. Please mind, that the free Heroku instance is used, so it can take some time when loading the page
+> for the first time.
 
 ## Features
 * Inventory managment of your electronic parts. Each part can be assigned to a category, footprint, manufacturer 

docs/installation/choosing_database.md

@@ -9,6 +9,7 @@ nav_order: 1
 
 Part-DB saves its data in a [relational (SQL) database](https://en.wikipedia.org/wiki/Relational_database). Part-DB supports either the use of [SQLite](https://www.sqlite.org/index.html) or [MySQL](https://www.mysql.com/) / [MariaDB](https://mariadb.org/) (which are mostly the same, except for some minor differences).
 
+{: .important }
 You have to choose between the database types before you start using Part-DB and **you can not change it (easily) after you have started creating data**. So you should choose the database type for your usecase (and possible future uses).
 
 ## Comparison

docs/installation/installation_docker.md

@@ -2,23 +2,33 @@
 title: Installation using Docker
 layout: default
 parent: Installation
+nav_order: 2
 ---
 
 # Installation of Part-DB via docker
 
-**Warning: The methods described here, configure PHP without HTTPS and therefore should only be used locally. If you want to expose Part-DB to the internet, you have to configure a reverse proxy!**
+{: .warning }
+> The methods described here, configure PHP without HTTPS and therefore should only be used locally in a trusted network.
+> If you want to expose Part-DB to the internet, you have to configure a reverse proxy with an SSL certificate!
 
 ## Docker-compose
 Part-DB can be installed via docker. A pre-built docker image is available under [jbtronics/part-db1](https://hub.docker.com/repository/docker/jbtronics/part-db1/).
 In the moment the master tag should be used (which is built from the latest commits in the master branch), as no tagged releases are available yet.
 
 The easiest way to use it is to use the docker-compose.yml available [here](https://raw.githubusercontent.com/Part-DB/Part-DB-symfony/master/docs/docker/docker-compose.yaml):
-0. Install docker and docker-compose like described under https://docs.docker.com/compose/install/
+1. Install docker and docker-compose like described under https://docs.docker.com/compose/install/
-1. Create a folder where the Part-DB data should live
+2. Create a folder where the Part-DB data should live
-2. Download docker-compose.yml and move it to the folder created above
+3. Download docker-compose.yml and move it to the folder created above
-3. Inside the folder, run `docker-compose up -d`
+4. Inside the folder, run
-4. Create the inital database with `docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate` and watch for the password output
+```bash
-5. Part-DB is available under `http://localhost:8080` and you can log in with username `admin` and the password shown before
+   docker-compose up -d
+```    
+5. Create the inital database with 
+ ```bash
+docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate
+ ```
+and watch for the password output
+6. Part-DB is available under `http://localhost:8080` and you can log in with username `admin` and the password shown before
 
 The docker image uses a SQLite database and all data (database, uploads and other media) is put into folders relative to the docker-compose.yml.
 

docs/installation/installation_guide-debian.md

@@ -2,13 +2,17 @@
 title: Direct Installation on Debian 11
 layout: default
 parent: Installation
+nav_order: 4
 ---
 
 # Part-DB installation guide for Debian 11 (Bullseye)
 This guide shows you how to install Part-DB directly on Debian 11 using apache2 and SQLite. This guide should work with recent Ubuntu and other Debian based distributions with little to no changes.
 Depending on what you want to do, using the prebuilt docker images may be a better choice, as you dont need to install this much dependencies. See **TODO** for more information of the docker installation.
 
-**Caution: This guide shows you how to install Part-DB for use in a trusted local network. If you want to use Part-DB on the internet, you HAVE TO setup a SSL certificate for your connection!**
+{: .warning }
+> The methods described here, configure PHP without HTTPS and therefore should only be used locally in a trusted network.
+> If you want to expose Part-DB to the internet, you HAVE to configure an SSL connection!
+
 
 ## Install prerequisites
 For the installation of Part-DB, we need some prerequisites. They can be installed by running the following command:
@@ -102,6 +106,12 @@ sudo yarn install
 sudo yarn build
 ```
 
+### Clear cache
+To ensure everything is working, clear the cache:
+```bash
+sudo -u www-data php bin/console cache:clear
+```
+
 ### Check if everything is installed
 To check if everything is installed, run the following command:
 ```bash

docs/installation/nginx.md

@@ -0,0 +1,67 @@
+---
+title: Nginx
+layout: default
+parent: Installation
+nav_order: 10
+---
+
+# Nginx
+You can also use [nginx](https://www.nginx.com/) as webserver for Part-DB. Setup Part-DB with apache is a bit easier, so
+this is the method shown in the guides. This guide assumes that you already have a working nginx installation with PHP
+configured.
+
+## Setup
+1. Install composer and yarn like described in the [apache guide]({% link installation/installation_guide-debian.md %}#install-composer).
+2. Create a folder for Part-DB and install and configure it as described
+3. Instead of creating the config for apache, add the following snippet to your nginx config:
+```nginx
+server {
+    # Redirect all HTTP requests to HTTPS
+    listen 80;
+    # Change this to your domain
+    server_name parts.example.com;
+    return 301 https://$host$request_uri;
+}
+server {
+#   listen 80;
+    listen 443 ssl;
+    
+    # Change this to your domain
+    server_name parts.example.com;
+    # /var/www/partdb/ should be the path to the folder where you installed Part-DB
+    root /var/www/partdb/public;
+
+    location / {
+        try_files $uri /index.php$is_args$args;
+    }
+
+    location ~ ^/index\.php(/|$) {
+        fastcgi_pass unix:/var/run/php/php-fpm.sock;
+        fastcgi_split_path_info ^(.+\.php)(/.+)$;
+        include fastcgi_params;
+        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
+        fastcgi_param DOCUMENT_ROOT $realpath_root;
+
+        internal;
+    }
+
+    location ~ \.php$ {
+        return 404;
+    }
+
+    error_log /var/log/nginx/parts.error.log;
+    access_log /var/log/nginx/parts.access.log;
+
+    # SSL parameters
+    ssl_certificate /var/www/certs/SSL/domain.cert.pem;
+    ssl_certificate_key /var/www/certs/SSL/private.key.pem;
+    ssl_trusted_certificate /var/www/certs/SSL/intermediate.cert.pem;
+
+    ssl_session_timeout 5m;
+
+    ssl_protocols TLSv1.2;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+}
+```
+4. Restart nginx with `sudo systemctl restart nginx` and you should be able to access Part-DB under your configured domain.

docs/serve.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+#
+# This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
+#
+#  Copyright (C) 2019 - 2023 Jan Böhmer (https://github.com/jbtronics)
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Affero General Public License as published
+#  by the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Affero General Public License for more details.
+#
+#  You should have received a copy of the GNU Affero General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+# Serve the documentation locally with jekyll
+bundle exec jekyll serve --config "_config.yaml,_config_dev.yaml" --livereload --watch

docs/usage/console_commands.md

@@ -0,0 +1,36 @@
+---
+title: Console commands
+layout: default
+parent: Usage
+---
+
+# Console commands
+
+Part-DB provides some console commands to display various information or perform some tasks.
+The commands are invoked from the main directory of Part-DB with the command `php bin/console [command]` in the context
+of the database user (so usually the webserver user), so you maybe have to use `sudo` or `su` to execute the commands.
+
+You can get help for every command with the parameter `--help`. See `php bin/console` for a list of all available commands.
+
+## User managment commands
+* `php bin/console partdb:users:list`: List all users of this Part-DB instance
+* `php bin/console partdb:users:set-password [username]`: Set/Changes the password of the user with the given username. This allows administrators to reset a password of a user, if he forgot it.
+* `php bin/console partdb:users:enable [username]`: Enable/Disable the user with the given username (use `--disable` to disable the user, which prevents login)
+* `php bin/console partdb:users:permissions`: View/Change the permissions of the user with the given username
+* `php bin/console partdb:users:upgrade-permissions-schema`: Upgrade the permissions schema of users to the latest version (this is normally automatically done when the user visits a page)
+* `php bin/console partdb:logs:show`: Show the most recent entries of the Part-DB event log / recent activity
+
+## Currency commands
+* `php bin/console partdb:currencies:update-exchange-rates`: Update the exchange rates of all currencies from the internet)
+
+## Installation/Maintenance commands
+* `php bin/console partdb:backup`: Backup the database and the attachments
+* `php bin/console partdb:version`: Display the current version of Part-DB and the used PHP version
+* `php bin/console partdb:check-requirements`: Check if the requirements for Part-DB are met (PHP version, PHP extensions, etc.) and make suggestions what could be improved
+* `partdb:migrations:convert-bbcode`: Migrate the old BBCode markup codes used in legacy Part-DB versions (< 1.0.0) to the new markdown syntax
+* `partdb:attachments:clean-unused`: Remove all attachments which are not used by any database entry (e.g. orphaned attachments)
+* `partdb:cache:clear`: Clears all caches, so the next page load will be slower, but the cache will be rebuild. This can maybe fix some issues, when the cache were corrupted. This command is also needed after changing things in the `parameters.yaml` file or upgrading Part-DB.
+
+## Database commands
+* `php bin/console doctrine:migrations:migrate`: Migrate the database to the latest version
+* `php bin/console doctrine:migrations:up-to-date`: Check if the database is up-to-date

docs/usage/labels.md

@@ -1,11 +1,21 @@
 ---
-title: Backup & Restore Data
+title: Labels
 layout: default
 parent: Usage
 ---
 
 # Labels
 
+Part-DB support the generation and printing of labels for parts, part lots and storelocation. 
+You can use the "Tools -> Labelgenerator" menu entry to create labels, or click the label generation link on the part.
+
+You can define label templates by creating Label profiles. This way you can create many similar looking labels with for
+many parts.
+
+The content of the labels is defined by the templates content field. You can use the WYSIWYG editor to create and style the content (or write HTML code).
+Using the "Label placeholder" menu in the editor, you can insert placeholders for the data of the parts.
+It will be replaced by the concrete data when the label is generated.
+ 
 ## Label placeholders
 A placeholder has the format `[[PLACEHOLDER]]` and will be filled with the concrete data by Part-DB.
 You can use the "Placeholders" dropdown in content editor, to automatically insert the placeholders.
@@ -20,6 +30,7 @@ You can use the "Placeholders" dropdown in content editor, to automatically inse
 | `[[DATE]]`  | The current date in the selected locale  | 31.12.2017 |
 | `[[TIME]]` | The current time in the selected locale | 18:34:11 |
 | `[[INSTALL_NAME]]` | The name of the current installation (see $config['partdb_title']) | Part-DB |
+| `[[INSTANCE_URL]]` | The URL of the current installation | https://demo.part-db.de | 
 
 ### Parts
 
@@ -45,6 +56,7 @@ You can use the "Placeholders" dropdown in content editor, to automatically inse
 | `[[CREATION_DATE]]` | The datetime when the element was created  | 2/26/16, 5:38 PM |
 
 ### Part lot
+
 | Placeholder  | Description  | Example  |
 |---|---|---|
 | `[[LOT_ID]]`   | Part lot ID | 123  |
@@ -56,6 +68,7 @@ You can use the "Placeholders" dropdown in content editor, to automatically inse
 | `[[LOCATION_FULL]]` | The full path of the storage location | Location -> Location A |
 
 ### Storelocation
+
 | Placeholder  | Description  | Example  |
 |---|---|---|
 | `[[ID]]` | ID of the storage location |  |
@@ -69,6 +82,7 @@ You can use the "Placeholders" dropdown in content editor, to automatically inse
 | `[[CREATION_DATE]]` | The datetime when the element was created  | 2/26/16, 5:38 PM |
 
 ## Twig mode
+
 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 }}`):