Improve documentation clarity and fix outdated information (#1129)

* Initial plan

* Improve documentation clarity, fix typos, and update outdated information

Co-authored-by: jbtronics <[email protected]>

* Replace LCSC with Mouser in cloud providers list per d-buchmann's review

Co-authored-by: jbtronics <[email protected]>

* Remove outdated Mouser API issue notice

Removed outdated information about the Mouser API's current issues with datasheets and part specifications.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jbtronics <[email protected]>
Co-authored-by: Jan Böhmer <[email protected]>

Author: Copilot

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # How to contribute
 
-Thank you for consider to contribute to Part-DB!
-Please read the text below, so your contributed content can be contributed easily to Part-DB.
+Thank you for considering contributing to Part-DB!
+Please read the text below, so your contributed content can be incorporated into Part-DB easily.
 
 You can contribute to Part-DB in various ways:
 * Report bugs and request new features via [issues](https://github.com/Part-DB/Part-DB-server/issues)
@@ -18,38 +18,38 @@ Part-DB uses translation keys (e.g. part.info.title) that are sorted by their us
 was translated in other languages (this is possible via the "Other languages" dropdown in the translation editor).
 
 ## Project structure
-Part-DB uses symfony's recommended [project structure](https://symfony.com/doc/current/best_practices.html).
+Part-DB uses Symfony's recommended [project structure](https://symfony.com/doc/current/best_practices.html).
 Interesting folders are:
 * `public`: Everything in this directory will be publicly accessible via web. Use this folder to serve static images.
-* `assets`: The frontend assets are saved here. You can find the javascript and CSS code here.
-* `src`: Part-DB's PHP code is saved here. Note that the sub directories are structured by the classes purposes (so use `Controller` Controllers, `Entities` for Database models, etc.)
-* `translations`: The translations used in Part-DB are saved here
+* `assets`: The frontend assets are saved here. You can find the JavaScript and CSS code here.
+* `src`: Part-DB's PHP code is saved here. Note that the subdirectories are structured by the classes' purposes (so use `Controller` for Controllers, `Entity` for Database models, etc.)
+* `translations`: The translations used in Part-DB are saved here.
 * `templates`: The templates (HTML) that are used by Twig to render the different pages. Email templates are also saved here.
-* `tests/`: Tests that can be run by PHPunit.
+* `tests/`: Tests that can be run by PHPUnit.
 
 ## Development environment
-For setting up an development you will need to install PHP, composer, a database server (MySQL or MariaDB) and yarn (which needs an nodejs environment).
-* Copy `.env` to `.env.local` and change `APP_ENV` to `APP_ENV=dev`. That way you will get development tools (symfony profiler) and other features that
+For setting up a development environment, you will need to install PHP, Composer, a database server (MySQL or MariaDB) and yarn (which needs a Node.js environment).
+* Copy `.env` to `.env.local` and change `APP_ENV` to `APP_ENV=dev`. That way you will get development tools (Symfony profiler) and other features that
 will simplify development.
-* Run `composer install` (without -o) to install PHP dependencies and `yarn install` to install frontend dependencies
-* Run `yarn watch`. The program will run in the background and compile the frontend files whenever you change something in the CSS or TypeScript files
-* For running Part-DB it is recommended to use [Symfony CLI](https://symfony.com/download). 
-That way you can run a correct configured webserver with `symfony serve`
+* Run `composer install` (without -o) to install PHP dependencies and `yarn install` to install frontend dependencies.
+* Run `yarn watch`. The program will run in the background and compile the frontend files whenever you change something in the CSS or TypeScript files.
+* For running Part-DB, it is recommended to use [Symfony CLI](https://symfony.com/download). 
+That way you can run a correctly configured webserver with `symfony serve`.
 
 ## Coding style
-Code should follow the [PSR12-Standard](https://www.php-fig.org/psr/psr-12/) and symfony's [coding standards](https://symfony.com/doc/current/contributing/code/standards.html).
+Code should follow the [PSR-12 Standard](https://www.php-fig.org/psr/psr-12/) and Symfony's [coding standards](https://symfony.com/doc/current/contributing/code/standards.html).
 
 Part-DB uses [Easy Coding Standard](https://github.com/symplify/easy-coding-standard) to check and fix coding style violations:
-* To check your code for valid code style run `vendor/bin/ecs check src/`
-* To fix violations run `vendor/bin/ecs check src/` (please checks afterwards if the code is valid afterwards)
+* To check your code for valid code style, run `vendor/bin/ecs check src/`
+* To fix violations, run `vendor/bin/ecs check src/ --fix` (please check afterwards if the code is still valid)
 
 ## GitHub actions
-Part-DB uses GitHub actions to run various tests and checks on the code:
+Part-DB uses GitHub Actions to run various tests and checks on the code:
 * Yarn dependencies can compile
-* PHPunit tests run successful
-* Config files, translations and templates has valid syntax
-* Doctrine schema valid
+* PHPUnit tests run successfully
+* Config files, translations, and templates have valid syntax
+* Doctrine schema is valid
 * No known vulnerable dependencies are used
-* Static analysis successful (phpstan with `--level=2`)
+* Static analysis is successful (phpstan with `--level=2`)
 
-Further the code coverage of the PHPunit tests is determined and uploaded to [CodeCov](https://codecov.io/gh/Part-DB/Part-DB-server).
+Further, the code coverage of the PHPUnit tests is determined and uploaded to [CodeCov](https://codecov.io/gh/Part-DB/Part-DB-server).

README.md

@@ -142,7 +142,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
+* [Symfony 6](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
 * [Hotwire Stimulus](https://stimulus.hotwired.dev/) and [Hotwire Turbo](https://turbo.hotwired.dev/): Frontend

docs/api/intro.md

@@ -46,7 +46,7 @@ See [Authentication chapter]({% link api/authentication.md %}) for more details.
 
 The API is split into different endpoints, which are reachable under the `/api/` path of your Part-DB instance (
 e.g. `https://your-part-db.local/api/`).
-There are various endpoints for each entity type (like `part`, `manufacturer`, etc.), which allow you to read and write data, and some special endpoints like `search` or `statistics`.
+There are various endpoints for each entity type (like `parts`, `manufacturers`, etc.), which allow you to read and write data, and some special endpoints like `search` or `statistics`.
 
 For example, all API endpoints for managing categories are available under `/api/categories/`. Depending on the exact
 path and the HTTP method used, you can read, create, update or delete categories.
@@ -56,7 +56,7 @@ For most entities, there are endpoints like this:
 * **POST**: `/api/categories/` - Create a new category
 * **GET**: `/api/categories/{id}` - Get a specific category by its ID
 * **DELETE**: `/api/categories/{id}` - Delete a specific category by its ID
-* **UPDATE**: `/api/categories/{id}` - Update a specific category by its ID. Only the fields which are sent in the
+* **PATCH**: `/api/categories/{id}` - Update a specific category by its ID. Only the fields which are sent in the
   request are updated, all other fields are left unchanged.
   Be aware that you have to set the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) content type
   header (`Content-Type: application/merge-patch+json`) for this to work.

docs/concepts.md

@@ -23,14 +23,14 @@ each other so that it does not matter which one of your 1000 things of Part you
 A part entity has many fields, which can be used to describe it better. Most of the fields are optional:
 
 * **Name** (Required): The name of the part or how you want to call it. This could be a manufacturer-provided name, or a
-  name you thought of yourself. Each name needs to be unique and must exist in a single category.
+  name you thought of yourself. Each name needs to be unique and must exist in a single category only.
 * **Description**: A short (single-line) description of what this part is/does. For longer information, you should use
   the comment field or the specifications
 * **Category** (Required): The category (see there) to which this part belongs to.
 * **Tags**: The list of tags this part belongs to. Tags can be used to group parts logically (similar to the category),
   but tags are much less strict and formal (they don't have to be defined beforehand) and you can assign multiple tags to
   a part. When clicking on a tag, a list with all parts which have the same tag, is shown.
-* **Min Instock**: *Not really implemented yet*. Parts where the total instock is below this value, will show up for
+* **Min Instock**: *Not fully implemented yet*. Parts where the total instock is below this value will show up for
   ordering.
 * **Footprint**: See there. Useful especially for electronic parts, which have one of the common electronic footprints (
   like DIP8, SMD0805 or similar). If a part has no explicitly defined preview picture, the preview picture of its
@@ -48,9 +48,9 @@ A part entity has many fields, which can be used to describe it better. Most of
   completely trustworthy.
 * **Favorite**: Parts with this flag are highlighted in parts lists
 * **Mass**: The mass of a single piece of this part (so of a single transistor). Given in grams.
-* **Internal Part number** (IPN): Each part is automatically assigned a numerical ID that identifies a part in the
-  database. This ID depends on when a part was created and can not be changed. If you want to assign your own unique
-  identifiers, or sync parts identifiers with the identifiers of another database you can use this field.
+* **Internal Part Number** (IPN): Each part is automatically assigned a numerical ID that identifies a part in the
+  database. This ID depends on when a part was created and cannot be changed. If you want to assign your own unique
+  identifiers, or sync parts identifiers with the identifiers of another database, you can use this field.
 
 ### Stock / Part lot
 
@@ -99,12 +99,12 @@ possible category tree could look like this:
 
 ### Supplier
 
-A Supplier is a vendor/distributor where you can buy/order parts. Price information of parts is associated with a
+A supplier is a vendor/distributor where you can buy/order parts. Price information of parts is associated with a
 supplier.
 
 ### Manufacturer
 
-A manufacturer represents the company that manufacturers/builds various parts (not necessarily sell them). If the
+A manufacturer represents the company that manufactures/builds various parts (not necessarily sells them). If the
 manufacturer also sells the parts, you have to create a supplier for that.
 
 ### Storage location

docs/configuration.md

@@ -6,7 +6,7 @@ nav_order: 5
 
 # Configuration
 
-Part-DBs behavior can be configured to your needs. There are different kinds of configuration options: Options, which are
+Part-DB's behavior can be configured to your needs. There are different kinds of configuration options: Options that are
 user-changeable (changeable dynamically via frontend), options that can be configured by environment variables, and
 options that are only configurable via Symfony config files.
 
@@ -40,8 +40,8 @@ The following configuration options can only be changed by the server administra
 variables, changing the `.env.local` file or setting env for your docker container. Here are just the most important
 options listed, see `.env` file for the full list of possible env variables.
 
-Environment variables allow to overwrite settings in the web interface. This is useful, if you want to enforce certain
-settings to be unchangable by users, or if you want to configure settings in a central place in a deployed environment.
+Environment variables allow you to overwrite settings in the web interface. This is useful if you want to enforce certain
+settings to be unchangeable by users, or if you want to configure settings in a central place in a deployed environment.
 On the settings page, you can hover over a setting to see, which environment variable can be used to overwrite it, it 
 is shown as tooltip. API keys or similar sensitive data which is overwritten by env variables, are redacted on the web
 interface, so that even administrators cannot see them (only the last 2 characters and the length).
@@ -105,11 +105,11 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
     * `part_delete`: Delete operation of an existing part
     * `part_create`: Creation of a new part
     * `part_stock_operation`: Stock operation on a part (therefore withdraw, add or move stock)
-    * `datastructure_edit`: Edit operation of an existing datastructure (e.g. category, manufacturer, ...)
-    * `datastructure_delete`: Delete operation of a existing datastructure (e.g. category, manufacturer, ...)
-    * `datastructure_create`: Creation of a new datastructure (e.g. category, manufacturer, ...)
-* `CHECK_FOR_UPDATES` (default `1`): Set this to 0, if you do not want Part-DB to connect to GitHub to check for new
-  versions, or if your server can not connect to the internet.
+    * `datastructure_edit`: Edit operation of an existing data structure (e.g. category, manufacturer, ...)
+    * `datastructure_delete`: Delete operation of an existing data structure (e.g. category, manufacturer, ...)
+    * `datastructure_create`: Creation of a new data structure (e.g. category, manufacturer, ...)
+* `CHECK_FOR_UPDATES` (default `1`): Set this to 0 if you do not want Part-DB to connect to GitHub to check for new
+  versions, or if your server cannot connect to the internet.
 * `APP_SECRET` (env only): This variable is a configuration parameter used for various security-related purposes,
   particularly for securing and protecting various aspects of your application. It's a secret key that is used for
   cryptographic operations and security measures (session management, CSRF protection, etc..). Therefore this
@@ -262,10 +262,10 @@ 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 need,
-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 be  completely removed in future versions of Part-DB.
+You can also configure some options via the `config/parameters.yaml` file. This should normally not be 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 merges 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 be 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`.

docs/index.md

@@ -27,31 +27,31 @@ It is installed on a web server and so can be accessed with any browser without
 * Inventory management of your electronic parts. Each part can be assigned to a category, footprint, manufacturer,
   and multiple store locations and price information. Parts can be grouped using tags. You can associate various files
   like datasheets or pictures with the parts.
-* Multi-language support (currently German, English, Russian, Japanese and French (experimental))
-* Barcodes/Labels generator for parts and storage locations, scan barcodes via webcam using the builtin barcode scanner
-* User system with groups and detailed (fine granular) permissions.
+* Multi-language support (currently German, English, Russian, Japanese, French, Czech, Danish, and Chinese)
+* Barcodes/Labels generator for parts and storage locations, scan barcodes via webcam using the built-in barcode scanner
+* User system with groups and detailed (fine-grained) permissions.
   Two-factor authentication is supported (Google Authenticator and Webauthn/U2F keys) and can be enforced for groups.
-  Password reset via email can be setup.
+  Password reset via email can be set up.
 * Optional support for single sign-on (SSO) via SAML (using an intermediate service
   like [Keycloak](https://www.keycloak.org/) you can connect Part-DB to an existing LDAP or Active Directory server)
 * Import/Export system
 * Project management: Create projects and assign parts to the bill of material (BOM), to show how often you could build
   this project and directly withdraw all components needed from DB
-* Event log: Track what changes happens to your inventory, track which user does what. Revert your parts to older
+* Event log: Track what changes happen to your inventory, track which user does what. Revert your parts to older
   versions.
-* Responsive design: You can use Part-DB on your PC, your tablet and your smartphone using the same interface.
+* Responsive design: You can use Part-DB on your PC, your tablet, and your smartphone using the same interface.
 * MySQL, SQLite and PostgreSQL are supported as database backends
 * Support for rich text descriptions and comments in parts
 * Support for multiple currencies and automatic update of exchange rates supported
 * Powerful search and filter function, including parametric search (search for parts according to some specifications)
 * Easy migration from an existing PartKeepr instance (see [here]({%link partkeepr_migration.md %}))
-* Use cloud providers (like Octopart, Digikey, Farnell or TME) to automatically get part information, datasheets and
+* Use cloud providers (like Octopart, Digikey, Farnell, Mouser, or TME) to automatically get part information, datasheets, and
   prices for parts (see [here]({% link usage/information_provider_system.md %}))
 * API to access Part-DB from other applications/scripts
-* [Integration with KiCad]({%link usage/eda_integration.md %}): Use Part-DB as central datasource for your
-  KiCad and see available   parts from Part-DB directly inside KiCad.
+* [Integration with KiCad]({%link usage/eda_integration.md %}): Use Part-DB as the central datasource for your
+  KiCad and see available parts from Part-DB directly inside KiCad.
 
-With these features Part-DB is useful to hobbyists, who want to keep track of their private electronic parts inventory,
+With these features, Part-DB is useful to hobbyists, who want to keep track of their private electronic parts inventory,
 or makerspaces, where many users should have (controlled) access to the shared inventory.
 
 Part-DB is also used by small companies and universities for managing their inventory.
@@ -67,11 +67,11 @@ See [LICENSE](https://github.com/Part-DB/Part-DB-symfony/blob/master/LICENSE) fo
 ## Donate for development
 
 If you want to donate to the Part-DB developer, see the sponsor button in the top bar (next to the repo name).
-There you will find various methods to support development on a monthly or a one time base.
+There you will find various methods to support development on a monthly or a one-time basis.
 
 ## Built with
 
-* [Symfony 5](https://symfony.com/): The main framework used for the serverside PHP
+* [Symfony 6](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
 * [Hotwire Stimulus](https://stimulus.hotwired.dev/) and [Hotwire Turbo](https://turbo.hotwired.dev/): Frontend

docs/installation/index.md

@@ -8,4 +8,4 @@ has_children: true
 # Installation
 Below you can find some guides to install Part-DB.
 
-For the hobbyists without much experience, we recommend the docker installation or direct installation on debian.
+For hobbyists without much experience, we recommend the Docker installation or direct installation on Debian.