holm/Part-DB-server
1
0
Fork 0
forked from mirror/Part-DB.Part-DB-server
Code Pull requests Activity

Fixed more typos and grammar issues in docs

Browse source
This commit is contained in:
Jan Böhmer 2024-02-23 14:26:17 +01:00
parent 5d68922f2e
commit 861c0174df
10 changed files with 164 additions and 169 deletions
Download patch file Download diff file Expand all files Collapse all files

39
docs/usage/information_provider_system.md
View file

@ -6,11 +6,11 @@ parent: Usage
# Information provider system
Part-DB can create parts based on information from external sources: For example with the right setup you can just
Part-DB can create parts based on information from external sources: For example, with the right setup you can just
search for a part number
and Part-DB will query selected distributors and manufacturers for the part and create a part with the information it
found.
This way your Part-DB parts automatically get datasheet links, prices, parameters and more, with just a few clicks.
This way your Part-DB parts automatically get datasheet links, prices, parameters, and more, with just a few clicks.
## Usage
@ -45,13 +45,13 @@ part.
Part-DB tries to automatically find existing elements from your database for the information it got from the providers
for fields like manufacturer, footprint, etc.
For this it searches for an element with the same name (case-insensitive) as the information it got from the provider. So
e.g. if the provider returns "EXAMPLE CORP" as manufacturer,
For this, it searches for an element with the same name (case-insensitive) as the information it got from the provider. So
e.g. if the provider returns "EXAMPLE CORP" as the manufacturer,
Part-DB will automatically select the element with the name "Example Corp" from your database.
As the names of these fields differ from provider to provider (and maybe not even normalized for the same provider), you
can define multiple alternative names for an element (on their editing page).
For example if define a manufacturer "Example Corp" with the alternative names "Example Corp.", "Example Corp", "Example
For example, if you define a manufacturer "Example Corp" with the alternative names "Example Corp.", "Example Corp", "Example
Corp. Inc." and "Example Corporation",
then the provider can return any of these names and Part-DB will still automatically select the right element.
@ -72,12 +72,12 @@ add the alternative names "Datasheet" and "Image" to the alternative names field
The system tries to be as flexible as possible, so many different information sources can be used.
Each information source is called am "info provider" and handles the communication with the external source.
The providers are just a driver which handles the communication with the different external sources and converts them
The providers are just a driver that handles the communication with the different external sources and converts them
into a common format Part-DB understands.
That way it is pretty easy to create new providers as they just need to do very little work.
Normally the providers utilize an API of a service, and you need to create an account at the provider and get an API key.
Also, there are limits on how many requests you can do per day or months, depending on the provider and your contract
Also, there are limits on how many requests you can do per day or month, depending on the provider and your contract
with them.
The following providers are currently available and shipped with Part-DB:
@ -86,8 +86,7 @@ The following providers are currently available and shipped with Part-DB:
### Octopart
The Octopart provider uses the [Octopart / Nexar API](https://nexar.com/api) to search for parts and getting
information.
The Octopart provider uses the [Octopart / Nexar API](https://nexar.com/api) to search for parts and get information.
To use it you have to create an account at Nexar and create a new application on
the [Nexar Portal](https://portal.nexar.com/).
The name does not matter, but it is important that the application has access to the "Supply" scope.
@ -100,7 +99,7 @@ can see your current usage on the Nexar portal.
Part-DB caches the search results internally, so if you have searched for a part before, it will not count against your
monthly limit again, when you create it from the search results.
Following env configuration options are available:
The following env configuration options are available:
* `PROVIDER_OCTOPART_CLIENT_ID`: The client ID you got from Nexar (mandatory)
* `PROVIDER_OCTOPART_SECRET`: The client secret you got from Nexar (mandatory)
@ -109,18 +108,18 @@ Following env configuration options are available:
Part-DB will save the prices in their native currency, and you can use Part-DB currency conversion feature to convert
it to your preferred currency.
* `PROVIDER_OCOTPART_COUNTRY`: The country you want to get prices in if available (optional, 2 letter ISO-code,
default: `DE`). To get correct prices, you have to set this and the currency setting to the correct value.
default: `DE`). To get the correct prices, you have to set this and the currency setting to the correct value.
* `PROVIDER_OCTOPART_SEARCH_LIMIT`: The maximum number of results to return per search (optional, default: `10`). This
affects how quickly your monthly limit is used up.
* `PROVIDER_OCTOPART_ONLY_AUTHORIZED_SELLERS`: If set to `true`, only offers
from [authorized sellers](https://octopart.com/authorized) will be returned (optional, default: `false`).
**Attention**: If you change the octopart clientID after you have already used the provider, you have to remove the
**Attention**: If you change the Octopart clientID after you have already used the provider, you have to remove the
OAuth token in the Part-DB database. Remove the entry in the table `oauth_tokens` with the name `ip_octopart_oauth`.
### Digi-Key
The Digi-Key provider uses the [Digi-Key API](https://developer.digikey.com/) to search for parts and getting shopping
The Digi-Key provider uses the [Digi-Key API](https://developer.digikey.com/) to search for parts and get shopping
information from [Digi-Key](https://www.digikey.com/).
To use it you have to create an account at Digi-Key and get an API key on
the [Digi-Key API page](https://developer.digikey.com/).
@ -128,7 +127,7 @@ You must create an organization there and create a "Production app". Most settin
grant access to the "Product Information" API.
You will get a Client ID and a Client Secret, which you have to put in the Part-DB env configuration (see below).
Following env configuration options are available:
The following env configuration options are available:
* `PROVIDER_DIGIKEY_CLIENT_ID`: The client ID you got from Digi-Key (mandatory)
* `PROVIDER_DIGIKEY_SECRET`: The client secret you got from Digi-Key (mandatory)
@ -138,7 +137,7 @@ Following env configuration options are available:
The Digi-Key provider needs an additional OAuth connection. To do this, go to the information provider
list (`https://your-partdb-instance.tld/tools/info_providers/providers`),
go the Digi-Key provider (in the disabled page) and click on the "Connect OAuth" button. You will be redirected to
go to Digi-Key provider (in the disabled page), and click on the "Connect OAuth" button. You will be redirected to
Digi-Key, where you have to log in and grant access to the app.
To do this your user needs the "Manage OAuth tokens" permission from the "System" section in the "System" tab.
The OAuth connection should only be needed once, but if you have any problems with the provider, just click the button
@ -146,13 +145,13 @@ again, to establish a new connection.
### TME
The TME provider use the API of [TME](https://www.tme.eu/) to search for parts and getting shopping information from
The TME provider uses the API of [TME](https://www.tme.eu/) to search for parts and getting shopping information from
them.
To use it you have to create an account at TME and get an API key on the [TME API page](https://developers.tme.eu/en/).
You have to generate a new anonymous key there and enter the key and secret in the Part-DB env configuration (see
below).
Following env configuration options are available:
The following env configuration options are available:
* `PROVIDER_TME_KEY`: The API key you got from TME (mandatory)
* `PROVIDER_TME_SECRET`: The API secret you got from TME (mandatory)
@ -171,7 +170,7 @@ You have to create an account at Farnell and get an API key on the [Farnell API
Register a new application there (settings does not matter, as long as you select the "Product Search API") and you will
get an API key.
Following env configuration options are available:
The following env configuration options are available:
* `PROVIDER_ELEMENT14_KEY`: The API key you got from Farnell (mandatory)
* `PROVIDER_ELEMENT14_STORE_ID`: The store ID you want to use. This decides the language of results, currency and
@ -185,11 +184,11 @@ information from [Mouser](https://www.mouser.com/).
You have to create an account at Mouser and register for an API key for the Search API on
the [Mouser API page](https://www.mouser.de/api-home/).
You will receive an API token, which you have to put in the Part-DB env configuration (see below):
At the registration you choose a country, language and currency in which you want to get the results.
At the registration you choose a country, language, and currency in which you want to get the results.
*Attention*: Currently (January 2024) the mouser API seems to be somewhat broken, in the way that it does not return any
information about datasheets and part specifications. Therefore Part-DB can not retrieve them, even if they are shown
at the mouser page. See [issue #503](https://github.com/Part-DB/Part-DB-server/issues/503) for more infos.
at the mouser page. See [issue #503](https://github.com/Part-DB/Part-DB-server/issues/503) for more info.
Following env configuration options are available:

4
docs/usage/keybindings.md
View file

@ -93,7 +93,7 @@ all text and search fields in Part-DB.
### Currency symbols
Please not the following keybindings are bound to a specific keycode. The key character is not the same on all
Please note, the following keybindings are bound to a specific keycode. The key character is not the same on all
keyboards.
It is given here for a US keyboard layout.
@ -108,7 +108,7 @@ For a German keyboard layout, replace ; with ö, and ' with ä.
### Others
Please not the following keybindings are bound to a specific keycode. The key character is not the same on all
Please note the following keybindings are bound to a specific keycode. The key character is not the same on all
keyboards.
It is given here for a US keyboard layout.

14
docs/usage/labels.md
View file

@ -7,12 +7,12 @@ parent: Usage
# Labels
Part-DB support the generation and printing of labels for parts, part lots and storage locations.
You can use the "Tools -> Label generator" menu entry to create labels, or click the label generation link on the part.
You can use the "Tools -> Label generator" 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
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 of the labels is defined by the template's 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.
@ -20,7 +20,7 @@ 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.
You can use the "Placeholders" dropdown in the content editor, to automatically insert the placeholders.
### Common
@ -124,12 +124,12 @@ the label generator settings:
The default used font (DejaVu) does not support all characters. Especially characters from non-latin languages like
Chinese, Japanese, Korean, Arabic, Hebrew, Cyrillic, etc. are not supported.
For this we use [Unifont](http://unifoundry.com/unifont.html) as fallback font. This font supports all (or most) unicode
characters, but is not as beautiful as DejaVu.
For this, we use [Unifont](http://unifoundry.com/unifont.html) as fallback font. This font supports all (or most) Unicode
characters but is not as beautiful as DejaVu.
If you want to use a different (more beautiful) font, you can use the [custom fonts](#use-custom-fonts-for-pdf-labels)
feature.
There is the [Noto](https://www.google.com/get/noto/) font family from Google, which supports a lot of languages and is
available in different styles (regular, bold, italic, bold-italic).
For example, you can use [Noto CJK](https://github.com/notofonts/noto-cjk) for more beautiful Chinese, Japanese
For example, you can use [Noto CJK](https://github.com/notofonts/noto-cjk) for more beautiful Chinese, Japanese,
and Korean characters.

40
docs/usage/tips_tricks.md
View file

@ -8,35 +8,35 @@ parent: Usage
Following you can find miscellaneous tips and tricks for using Part-DB.
## Create datastructures directly from part edit page
## Create data structures 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
Instead of first creating a category, manufacturer, footprint, etc., and then creating the part, you can create the
data structures directly from the part edit page: Just type the name of the data structure you want to create into the
select field on the part edit page and press "Create new ...". The new data structure 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",
You can create also create nested data structures 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
## Built-in 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.
Part-DB includes several built-in images for common footprints. You can use these images in your footprint
data structures,
by creating an attachment on the data structure and selecting it as the 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).
which you can find in the "Tools" menu (you may 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 fulfill. This allows you to search for parts with specific parameters (or parameter ranges), for example you
In the "parameters" tab of the filter panel on parts list page, you can define constraints, and which parameter values
have to fulfill. 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
## View own user's 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.
@ -49,10 +49,8 @@ part).
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:
equations, double dollar signs mark displayed equations (which will be their own line and centered).
For example, the following equation will be rendered as an inline equation:
```
$E=mc^2$
@ -77,16 +75,16 @@ free API used by default only supports the Euro as base currency.
## Enforce log comments
On almost any editing operation it is possible to add a comment describing, what or why you changed something.
This comment will be written to change log and can be viewed later.
If you want to enforce your users to add comments to certain operations, you can do this by setting
This comment will be written to changelog and can be viewed later.
If you want to force your users to add comments to certain operations, you can do this by setting
the `ENFORCE_CHANGE_COMMENTS_FOR` option.
See the configuration reference for more information.
## Personal stocks and stock locations
For makerspaces and universities with a lot of users, where each user can have his own stock, which only he should be
For maker spaces and universities with a lot of users, where each user can have his own stock, which only he should be
able to access, you can assign
the user as "owner" of a part lot. This way, only him is allowed to add or remove parts from this lot.
the user as "owner" of a part lot. This way, only he is allowed to add or remove parts from this lot.
## Update notifications