mirror/Part-DB.Part-DB-server
1
0
Fork 1
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2025-07-15 04:44:36 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Fixed some typos and grammar issues in documentation

Browse source
This commit is contained in:
Jan Böhmer 2024-02-23 13:56:23 +01:00
parent 20ee16e3c0
commit 5d68922f2e
11 changed files with 142 additions and 153 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/usage/backup_restore.md
View file

@ -7,8 +7,8 @@ parent: Usage
# Backup and Restore Data
When working productively you should back up the data and configuration of Part-DB regularly to prevent data loss. This
is also useful, if you want to migrate your Part-DB instance from one server to another. In that case you just have to
back up the data on server 1, move the backup to server 2, install Part-DB on server 2 and restore the backup.
is also useful if you want to migrate your Part-DB instance from one server to another. In that case, you just have to
back up the data on server 1, move the backup to server 2, install Part-DB on server 2, and restore the backup.
## Backup (automatic / Part-DB supported)
@ -23,11 +23,11 @@ To back up all possible data, run the following
command: `php bin/console partdb:backup --full /path/to/backup/partdb_backup.zip`.
It is possible to do only partial backups (config, attachments, or database). See `php bin/console partdb:backup --help`
for more infos about these options.
for more info about these options.
## Backup (manual)
There are 3 parts which have to be backup-ed: The configuration files, which contains the instance specific options, the
3 parts have to be backup-ed: The configuration files, which contain the instance-specific options, the
uploaded files of attachments, and the database containing the most data of Part-DB.
Everything else like thumbnails and cache files, are recreated automatically when needed.
@ -42,7 +42,7 @@ You have to recursively copy the `uploads/` folder and the `public/media` folder
### Database
#### Sqlite
#### SQLite
If you are using sqlite, it is sufficient to just copy your `app.db` from your database location (normally `var/app.db`)
to your backup location.
@ -55,8 +55,8 @@ interface (`mysqldump -uBACKUP -pPASSWORD DATABASE`)
## Restore
Install Part-DB as usual as described in the installation section, except the database creation / migration part. You
have to use the same database type (sqlite or mysql) as on the back-up server instance.
Install Part-DB as usual as described in the installation section, except for the database creation/migration part. You
have to use the same database type (SQLite or MySQL) as on the backuped server instance.
### Restore configuration
@ -69,7 +69,7 @@ Copy the `uploads/` and the `public/media/` folder from your backup into your ne
### Restore database
#### Sqlite
#### SQLite
Copy the backup-ed `app.db` into the database folder normally `var/app.db` in Part-DB root folder.

4
docs/usage/eda_integration.md
View file

@ -65,11 +65,11 @@ you need to define at least a symbol, footprint, reference prefix, or value on a
You can use the "Force visibility" checkbox on a part or category to override this behavior and force parts to be visible or hidden in KiCad.
*Please note that KiCad caches the library categories. So if you change something, which would change the visibile categories in KiCad, you have to reload EEschema to see the changes.*
*Please note that KiCad caches the library categories. So if you change something, which would change the visible categories in KiCad, you have to reload EEschema to see the changes.*
### Category depth in KiCad
For performance reasons, only the mmost top-level categories of Part-DB are shown as categories in KiCad. All parts in the subcategories are shown in the top-level category.
For performance reasons, only the most top-level categories of Part-DB are shown as categories in KiCad. All parts in the subcategories are shown in the top-level category.
You can configure the depth of the categories shown in KiCad, via the `EDA_KICAD_CATEGORY_DEPTH` env option. The default value is 0, which means only the top-level categories are shown.
To show more levels of categories, you can set this value to a higher number.

61
docs/usage/getting_started.md
View file

@ -18,22 +18,22 @@ Before you start creating data structures, you should configure Part-DB to your
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]({% link configuration.md %}).
A list of possible configuration options can be found [here]({% link configuration.md %}).
## Change password, Set up Two-Factor-Authentication & Customize User settings
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).
If you have not already done so, 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]({% 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)
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.
In the user settings panel, you can change account info 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]({% link assets/getting_started/user_settings.png %})
@ -46,7 +46,7 @@ used.
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:
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
@ -55,14 +55,14 @@ $E=mc^2$) or `$$` (like `$$E=mc^2$$`) which will be rendered as a block, like so
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 set up an own account, so that tracking of what user did what works
On this page you can create new users, change their passwords and settings, and change their permissions.
For each user who should use Part-DB you should set up their own account so that tracking of what user did works
properly.
![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
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]({% link assets/getting_started/user_permissions.png %})
@ -75,35 +75,34 @@ to restrict the permissions.
### Groups
If you have many users which should share the same permissions, it is useful to define the permissions using user
If you have many users who should share the same permissions, it is useful to define the permissions using user
groups, which you can create and edit in the `System -> Groups` menu.
By default 3 groups are defined:
By default, 3 groups are defined:
* `readonly` which users only have read permissions (like viewing, searching parts, attachments, etc.)
* `users` which users also have rights to edit/delete/create elements
* `admin` which users can do administrative operations (like creating new users, show global system log, etc.)
* `admin` which users can do administrative operations (like creating new users, showing global system log, etc.)
Users only use the setting of a capability from a group, if the user has a group associated and the capability on the
user is set to `inherit` (which is the default if creating a new user). You can override the permissions settings of a
group per user by explicitly settings the permission at the user.
group per user by explicitly setting the permission of the user.
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
To inherit the permissions from a parent group set the capability to inherit, otherwise, set it explicitly to override
the parents' permission.
## Create Attachment types
Every attachment (that is a 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.
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]({% link assets/getting_started/attachment_type_admin.png %})
Depending on your use case different entries here make sense. For part management the following (additional) entries
maybe make sense:
Depending on your use case different entries here make sense. For part management the following (additional) entries may make sense:
* Datasheets (restricted to pdfs, Allowed filetypes: `application/pdf`)
* Pictures (for generic pictures of components, storage locations, etc., Allowed filetypes: `image/*`
@ -111,34 +110,34 @@ maybe make sense:
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.
here. To allow all browser-supported images, you can use `image/*` wildcard here.
## (Optional) Create Currencies
If you want to save price information for parts in a currency different to your global currency (by default Euro), you
If you want to save price information for parts in a currency different from your global currency (by default Euro), you
have to define the additional currencies you want to use under `Edit -> Currencies`:
![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
You create a new currency, name it however you want (it is recommended to use the official name of the currency),
select the currency ISO code from the list, and save it. The currency symbol is determined automatically from the chosen ISO
code.
You can define an exchange rate in terms of your base currency (e.g. how many euros is one unit of your currency worth)
to convert the currencies values in your preferred display currency automatically.
to convert the currency values in your preferred display currency automatically.
## (Optional) Create 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.
box or books on a shelf.
However, if you want to manage things, that are divisible and the stock is described by a physical quantity, like
length for cables, or volumina of a liquid, you have to define additional measurement units.
length for cables, or volumes of a liquid, you have to define additional measurement units.
This is possible under `Edit -> Measurement Units`:
![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).
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.
@ -157,16 +156,16 @@ Every part has to be assigned to a category, so you should create at least one c
## (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.
They can be used to group parts by their physical shape and to find parts within 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.
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
You can define attachments here which are associated with the footprint. The attachment set as the 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

52
docs/usage/import_export.md
View file

@ -7,7 +7,7 @@ parent: Usage
# Import & Export data
Part-DB offers the possibility to import existing data (parts, datastructures, etc.) from existing data sources into
Part-DB offers the possibility to import existing data (parts, data structures, etc.) from existing data sources into
Part-DB. Data can also be exported from Part-DB into various formats.
## Import
@ -34,23 +34,23 @@ find in the "Tools" sidebar panel.
> You will not be able to check the data before it is written to the database, so you should review the data before
> using the import tool.
You can upload the file which should be imported here and choose various options on how the data should be treated:
You can upload the file that should be imported here and choose various options on how the data should be treated:
* **Format**: By default "auto" is selected here and Part-DB will try to detect the format of the file automatically
based on its file extension. If you want to force a specific format or Part-DB can not auto-detect the format, you can
select it here.
* **CSV delimiter**: If you upload an CSV file, you can select the delimiter character which is used to separate the
columns in the CSV file. Depending on the CSV file, this might be a comma (`,`), semicolon (`;`).
* **CSV delimiter**: If you upload a CSV file, you can select the delimiter character which is used to separate the
columns in the CSV file. Depending on the CSV file, this might be a comma (`,`) or semicolon (`;`).
* **Category override**: You can select (or create) a category here, to which all imported parts should be assigned, no
matter what was specified in the import file. This can be useful if you want to assign all imports to a certain
category or if no category is specified in the data. If you leave this field empty, the category will be determined by
the import file (or the export will error, if no category is specified).
* **Mark all imported parts as "Needs review"**: If this is selected, all imported parts will be marked as "Needs
review" after the import. This can be useful if you want to review all imported parts before using them.
* **Create unknown datastructures**: If this is selected Part-DB will create new datastructures (like categories,
manufacturers, etc.) if no datastructure(s) with the same name and path already exists. If this is not selected, only
existing datastructures will be used and if no matching datastrucure is found, the imported parts field will be empty.
* **Path delimiter**: Part-DB allows you to create/select nested datastructures (like categories, manufacturers, etc.)
* **Create unknown data structures**: If this is selected Part-DB will create new data structures (like categories,
manufacturers, etc.) if no data structure(s) with the same name and path already exists. If this is not selected, only
existing data structures will be used and if no matching data strucure is found, the imported parts field will be empty.
* **Path delimiter**: Part-DB allows you to create/select nested data structures (like categories, manufacturers, etc.)
by using a path (e.g. `Category 1->Category 1.1`, which will select/create the `Category 1.1` whose parent
is `Category 1`). This path is separated by the path delimiter. If you want to use a different path delimiter than the
default one (which is `>`), you can select it here.
@ -59,7 +59,7 @@ You can upload the file which should be imported here and choose various options
is not selected, the import will continue for the other parts and only the invalid parts will be skipped.
After you have selected the options, you can start the import by clicking the "Import" button. When the import is
finished, you will see the results of the import in the lower half of the page. You find a table with the imported
finished, you will see the results of the import in the lower half of the page. You can find a table with the imported
parts (including links to them) there.
#### Fields description
@ -83,14 +83,14 @@ leave them empty or do not include the column in your file.
* **`manufacturing_status`**: The manufacturing status of the part, must be one of the following
values: `announced`, `active`, `nrfnd`, `eol`, `discontinued` or left empty.
* **`needs_review`** or **`needs_review`**: If this is set to `1`, the part will be marked as "needs review".
* **`tags`**: A comma separated list of tags for the part.
* **`tags`**: A comma-separated list of tags for the part.
* **`mass`**: The mass of the part in grams.
* **`ipn`**: The IPN (Item Part Number) of the part.
* **`minamount`**: The minimum amount of the part which should be in stock.
* **`partUnit`**: The measurement unit of the part to use. Can be a path similar to the category field.
With the following fields you can specify storage locations and amount / quantity in stock of the part. An PartLot will
be created automatically from the data and assigned to the part. The following fields are helpers for an easy import for
With the following fields, you can specify storage locations and amount/quantity in stock of the part. A PartLot will
be created automatically from the data and assigned to the part. The following fields are helpers for an easy import of
parts at one storage location. If you need to create a Part with multiple PartLots you have to use JSON format (or CSV)
with nested objects:
@ -99,7 +99,7 @@ field.
**`amount`**, **`quantity`** or **`instock`**: The amount of the part in stock. If this value is not set, the part lot
will be marked with "unknown amount"
The following fields can be used to specify the supplier/distributor, supplier product number and the price of the part.
The following fields can be used to specify the supplier/distributor, supplier product number, and the price of the part.
This is only possible for a single supplier/distributor and price with these fields. If you need to specify multiple
suppliers/distributors or prices, you have to use JSON format (or CSV) with nested objects.
**Please note that the supplier fields is required, if you want to import prices or supplier product numbers**. If the
@ -125,31 +125,31 @@ give the user any additional information.
You can export data structures (like categories, manufacturers, etc.) in the respective edit page (e.g. Tools Panel ->
Edit -> Category).
If you select a certain datastructure from your list, you can export it (and optionally all sub-datastructures) in the "
If you select a certain data structure from your list, you can export it (and optionally all sub data structures) in the "
Export" tab.
If you want to export all datastructures of a certain type (e.g. all categories in your database), you can select the "
If you want to export all data structures of a certain type (e.g. all categories in your database), you can select the "
Export all" function in the "Import / Export" tab of the "new element" page.
You can select between the following export formats:
* **CSV** (Comma Separated Values): A semicolon separated list of values, where every line represents an element. This
* **CSV** (Comma Separated Values): A semicolon-separated list of values, where every line represents an element. This
format can be imported into Excel or LibreOffice Calc and is easy to work with. However, it does not support nested
datastructures or sub data (like parameters, attachments, etc.), very well (many columns are generated, as every
possible sub data is exported as a separate column).
data structures or sub data (like parameters, attachments, etc.), very well (many columns are generated, as every
possible sub-data is exported as a separate column).
* **JSON** (JavaScript Object Notation): A text-based format, which is easy to work with programming languages. It
supports nested datastructures and sub data (like parameters, attachments, etc.) very well. However, it is not easy to
work with in Excel or LibreOffice Calc and you maybe need to write some code to work with the exported data
supports nested data structures and sub-data (like parameters, attachments, etc.) very well. However, it is not easy to
work with in Excel or LibreOffice Calc and you may need to write some code to work with the exported data
efficiently.
* **YAML** (Yet another Markup Language): Very similar to JSON
* **XML** (Extensible Markup Language): Good support with nested datastructures. Similar use case as JSON and YAML.
* **YAML** (Yet Another Markup Language): Very similar to JSON
* **XML** (Extensible Markup Language): Good support with nested data structures. Similar use cases as JSON and YAML.
Also, you can select between the following export levels:
* **Simple**: This will only export very basic information about the name (like the name, or description for parts)
* **Extended**: This will export all commonly used information about this datastructure (like notes, options, etc.)
* **Full**: This will export all available information about this datastructure (like all parameters, attachments)
* **Extended**: This will export all commonly used information about this data structure (like notes, options, etc.)
* **Full**: This will export all available information about this data structure (like all parameters, attachments)
Please note that the level will also be applied to all sub data or children elements. So if you select "Full" for a
Please note that the level will also be applied to all sub-data or children elements. So if you select "Full" for a
part, all the associated categories, manufacturers, footprints, etc. will also be exported with all available
information, this can lead to very large export files.
@ -158,4 +158,4 @@ information, this can lead to very large export files.
You can export parts in all part tables. Select the parts you want via the checkbox in the table line and select the
export format and level in the appearing menu.
See the section about exporting datastructures for more information about the export formats and levels.
See the section about exporting data structures for more information about the export formats and levels.