templates
/
KiBot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[DOCs] Added help about the variant options 

- Generated by a new command line `--help-variants`

Related to #257
This commit is contained in:
Salvador E. Tropea 2022-09-15 07:13:33 -03:00
parent 76742bb69f
commit 3e03228b7b
8 changed files with 108 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
README.md
View File

@ -49,6 +49,7 @@
* [Supported filters](#supported-filters)
* [Examples for filters](#examples-for-filters)
* [Built-in filters](#built-in-filters)
* [Supported variants](#supported-variants)
* [Changing the 3D model, simple mechanism](#changing-the-3d-model-simple-mechanism)
* [Changing the 3D model, complex mechanism](#changing-the-3d-model-complex-mechanism)
* [DNF and DNC internal keys](#dnf-and-dnc-internal-keys)
@ -942,6 +943,82 @@ The [tests/yaml_samples](https://github.com/INTI-CMNB/KiBot/tree/master/tests/ya
Note that the **_kibom_...** filters uses a field named `Config`, but you can customise them invoking **_kibom_dnf_FIELD**. This will create an equivalent filter, but using the indicated **FIELD**.
#### Supported variants:
- `ibom`: IBoM variant style
The Config field (configurable) contains a value.
If this value matches with a value in the whitelist is included.
If this value matches with a value in the blacklist is excluded.
* Valid keys:
- `comment`: [string=''] A comment for documentation purposes.
- `dnc_filter`: [string|list(string)=''] Name of the filter to mark components as 'Do Not Change'.
Use '_kibom_dnc' for the default KiBoM behavior.
- `dnf_filter`: [string|list(string)=''] Name of the filter to mark components as 'Do Not Fit'.
Use '_kibom_dnf' for the default KiBoM behavior.
Use '_kicost_dnp'' for the default KiCost behavior.
- `exclude_filter`: [string|list(string)=''] Name of the filter to exclude components from BoM processing.
Use '_mechanical' for the default KiBoM behavior.
- `file_id`: [string=''] Text to use as the replacement for %v expansion.
- `name`: [string=''] Used to identify this particular variant definition.
- `pre_transform`: [string|list(string)=''] Name of the filter to transform fields before applying other filters.
Use '_var_rename' to transform VARIANT:FIELD fields.
Use '_var_rename_kicost' to transform kicost.VARIANT:FIELD fields.
Use '_kicost_rename' to apply KiCost field rename rules.
- `variant_field`: [string='Config'] Name of the field that stores board variant for component.
- `variants_blacklist`: [string|list(string)=''] List of board variants to exclude from the BOM.
- `variants_whitelist`: [string|list(string)=''] List of board variants to include in the BOM.
- `kibom`: KiBoM variant style
The Config field (configurable) contains a comma separated list of variant directives.
-VARIANT excludes a component from VARIANT.
+VARIANT includes the component only if we are using this variant.
* Valid keys:
- `comment`: [string=''] A comment for documentation purposes.
- `config_field`: [string='Config'] Name of the field used to classify components.
- `dnc_filter`: [string|list(string)=''] Name of the filter to mark components as 'Do Not Change'.
Use '_kibom_dnc' for the default KiBoM behavior.
- `dnf_filter`: [string|list(string)=''] Name of the filter to mark components as 'Do Not Fit'.
Use '_kibom_dnf' for the default KiBoM behavior.
Use '_kicost_dnp'' for the default KiCost behavior.
- `exclude_filter`: [string|list(string)=''] Name of the filter to exclude components from BoM processing.
Use '_mechanical' for the default KiBoM behavior.
- `file_id`: [string=''] Text to use as the replacement for %v expansion.
- `name`: [string=''] Used to identify this particular variant definition.
- `pre_transform`: [string|list(string)=''] Name of the filter to transform fields before applying other filters.
Use '_var_rename' to transform VARIANT:FIELD fields.
Use '_var_rename_kicost' to transform kicost.VARIANT:FIELD fields.
Use '_kicost_rename' to apply KiCost field rename rules.
- `variant`: [string|list(string)=''] Board variant(s).
- `kicost`: KiCost variant style
The `variant` field (configurable) contains one or more values.
If any of these values matches the variant regex the component is included.
By default a pre-transform filter is applied to support kicost.VARIANT:FIELD and
field name aliases used by KiCost.
Also a default `dnf_filter` implements the KiCost DNP mechanism.
* Valid keys:
- `comment`: [string=''] A comment for documentation purposes.
- `dnc_filter`: [string|list(string)=''] Name of the filter to mark components as 'Do Not Change'.
Use '_kibom_dnc' for the default KiBoM behavior.
- `dnf_filter`: [string|list(string)=''] Name of the filter to mark components as 'Do Not Fit'.
Use '_kibom_dnf' for the default KiBoM behavior.
Use '_kicost_dnp'' for the default KiCost behavior.
- `exclude_filter`: [string|list(string)=''] Name of the filter to exclude components from BoM processing.
Use '_mechanical' for the default KiBoM behavior.
- `file_id`: [string=''] Text to use as the replacement for %v expansion.
- `name`: [string=''] Used to identify this particular variant definition.
- `pre_transform`: [string|list(string)=''] Name of the filter to transform fields before applying other filters.
Use '_var_rename' to transform VARIANT:FIELD fields.
Use '_var_rename_kicost' to transform kicost.VARIANT:FIELD fields.
Use '_kicost_rename' to apply KiCost field rename rules.
- `separators`: [string=',;/ '] Valid separators for variants in the variant field.
Each character is a valid separator.
Only supported internally, don't use it if you plan to use KiCost.
- `variant`: [string=''] Variants to match (regex).
- `variant_field`: [string='variant'] Name of the field that stores board variant/s for component.
Only supported internally, don't use it if you plan to use KiCost.
#### Changing the 3D model, simple mechanism
This mechanism allows small changes to the 3D model. Is simple to use, but the information is located in the schematic.
@ -3576,6 +3653,7 @@ Usage:
kibot [-v...] --help-output=HELP_OUTPUT
kibot [-v...] --help-outputs
kibot [-v...] --help-preflights
kibot [-v...] --help-variants
kibot -h | --help
kibot --version
@ -3619,6 +3697,7 @@ Help options:
--help-output HELP_OUTPUT Help for this particular output
--help-outputs List supported outputs and details
--help-preflights List supported preflights and details
--help-variants List supported variants and details
```

5
docs/README.in
View File

@ -49,6 +49,7 @@
* [Supported filters](#supported-filters)
* [Examples for filters](#examples-for-filters)
* [Built-in filters](#built-in-filters)
* [Supported variants](#supported-variants)
* [Changing the 3D model, simple mechanism](#changing-the-3d-model-simple-mechanism)
* [Changing the 3D model, complex mechanism](#changing-the-3d-model-complex-mechanism)
* [DNF and DNC internal keys](#dnf-and-dnc-internal-keys)
@ -549,6 +550,10 @@ The [tests/yaml_samples](https://github.com/INTI-CMNB/KiBot/tree/master/tests/ya
Note that the **_kibom_...** filters uses a field named `Config`, but you can customise them invoking **_kibom_dnf_FIELD**. This will create an equivalent filter, but using the indicated **FIELD**.
#### @variants@
#### Changing the 3D model, simple mechanism
This mechanism allows small changes to the 3D model. Is simple to use, but the information is located in the schematic.

2
docs/replace_tags.pl
View File

@ -4,6 +4,7 @@ $outputs =`../src/kibot --help-outputs`;
$cmd_help=`../src/kibot --help`;
$preflight=`../src/kibot --help-preflights`;
$filters=`../src/kibot --help-filters`;
$variants=`../src/kibot --help-variants`;
$global_options=`../src/kibot --help-global-options`;
$dependencies=`../src/kibot --help-dependencies --markdown`;
$json_dep=`../src/kibot --help-dependencies --json`;
@ -15,6 +16,7 @@ while (<>)
$_ =~ s/\@cmd_help\@/$cmd_help/;
$_ =~ s/\@preflight\@/$preflight/;
$_ =~ s/\@filters\@/$filters/;
$_ =~ s/\@variants\@/$variants/;
$_ =~ s/\@global_options\@/$global_options/;
$_ =~ s/\@dependencies\@/$dependencies/;
$_ =~ s/\@json_dep\@/$json_dep/;

7
kibot/__main__.py
View File

@ -22,6 +22,7 @@ Usage:
kibot [-v...] --help-output=HELP_OUTPUT
kibot [-v...] --help-outputs
kibot [-v...] --help-preflights
kibot [-v...] --help-variants
kibot -h | --help
kibot --version
@ -65,6 +66,7 @@ Help options:
--help-output HELP_OUTPUT Help for this particular output
--help-outputs List supported outputs and details
--help-preflights List supported preflights and details
--help-variants List supported variants and details
"""
import os
@ -99,7 +101,7 @@ from .misc import EXIT_BAD_ARGS, W_VARCFG, NO_PCBNEW_MODULE, W_NOKIVER, hide_std
from .pre_base import BasePreFlight
from .error import KiPlotConfigurationError, config_error
from .config_reader import (CfgYamlReader, print_outputs_help, print_output_help, print_preflights_help, create_example,
print_filters_help, print_global_options_help, print_dependencies)
print_filters_help, print_global_options_help, print_dependencies, print_variants_help)
from .kiplot import (generate_outputs, load_actions, config_output, generate_makefile, generate_examples, solve_schematic,
solve_board_file, solve_project_file, check_board_file)
GS.kibot_version = __version__
@ -298,6 +300,9 @@ def main():
if args.help_preflights:
print_preflights_help()
sys.exit(0)
if args.help_variants:
print_variants_help()
sys.exit(0)
if args.help_filters:
print_filters_help()
sys.exit(0)

13
kibot/config_reader.py
View File

@ -21,6 +21,7 @@ from .misc import (NO_YAML_MODULE, EXIT_BAD_ARGS, EXAMPLE_CFG, WONT_OVERWRITE, W
from .gs import GS
from .registrable import RegOutput, RegVariant, RegFilter, RegDependency
from .pre_base import BasePreFlight
from .var_base import BaseVariant
from . import __pypi_deps__
# Logger
from . import log
@ -656,6 +657,18 @@ def print_preflights_help():
print_output_options(n, options, 2)
def print_variants_help():
vars = BaseVariant.get_registered()
logger.debug('{} supported variants'.format(len(vars)))
print('Supported variants:\n')
for n, o in OrderedDict(sorted(vars.items())).items():
help = o.__doc__
if help is None:
help = 'Undocumented'
print('- `{}`: {}.'.format(n, help.strip()))
print_output_options(n, o, 2)
def print_filters_help():
filters = RegFilter.get_registered()
logger.debug('{} supported filters'.format(len(filters)))

1
kibot/kicad/v5_sch.py
View File

@ -882,6 +882,7 @@ class SchematicComponent(object):
self.field_ref = ''
self.value = ''
self.footprint = ''
self.footprint_lib = None
self.datasheet = ''
self.desc = ''
self.fields = []

2
kibot/var_ibom.py
View File

@ -19,7 +19,7 @@ class IBoM(BaseVariant): # noqa: F821
""" IBoM variant style
The Config field (configurable) contains a value.
If this value matches with a value in the whitelist is included.
If this value matches with a value in the blacklist is excluded. """
If this value matches with a value in the blacklist is excluded """
def __init__(self):
super().__init__()
with document:

2
kibot/var_kibom.py
View File

@ -19,7 +19,7 @@ class KiBoM(BaseVariant): # noqa: F821
""" KiBoM variant style
The Config field (configurable) contains a comma separated list of variant directives.
-VARIANT excludes a component from VARIANT.
+VARIANT includes the component only if we are using this variant. """
+VARIANT includes the component only if we are using this variant """
def __init__(self):
super().__init__()
self._def_exclude_filter = None