From b7e4377029f9927476282751ba9902d5b4ed3033 Mon Sep 17 00:00:00 2001 From: "Salvador E. Tropea" Date: Tue, 10 Sep 2024 12:55:21 -0300 Subject: [PATCH] [DOCs][Updated ] Changelog and recent changes - Report template as extended choice - name/comment as basic for filters --- CHANGELOG.md | 1 + docs/samples/generic_plot.kibot.yaml | 5 +++-- docs/source/Changelog.rst | 5 +++++ docs/source/configuration/filters/expand_text_vars.rst | 4 ++-- docs/source/configuration/filters/field_modify.rst | 4 ++-- docs/source/configuration/filters/field_rename.rst | 4 ++-- docs/source/configuration/filters/generic.rst | 4 ++-- docs/source/configuration/filters/rot_footprint.rst | 4 ++-- docs/source/configuration/filters/separate_pins.rst | 4 ++-- docs/source/configuration/filters/spec_to_field.rst | 4 ++-- docs/source/configuration/filters/subparts.rst | 4 ++-- docs/source/configuration/filters/urlify.rst | 4 ++-- docs/source/configuration/filters/value_split.rst | 4 ++-- docs/source/configuration/filters/var_rename.rst | 4 ++-- docs/source/configuration/filters/var_rename_kicost.rst | 4 ++-- docs/source/configuration/outputs/ReportOptions.rst | 3 ++- 16 files changed, 35 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9be2cf31..5bea8fdb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Report: - Solder paste usage stats (#616) - Support for variants (See #616) + - Testpoints report (See #638) - xDRC: configurable category (#647) - Schematic: - Support for text boxes inside symbols (#621) diff --git a/docs/samples/generic_plot.kibot.yaml b/docs/samples/generic_plot.kibot.yaml index 93aa69fb..b9571320 100644 --- a/docs/samples/generic_plot.kibot.yaml +++ b/docs/samples/generic_plot.kibot.yaml @@ -3546,9 +3546,10 @@ outputs: solder_paste_metal_amount: 87.75 # [number=0.12] Stencil thickness in mm. Used to compute solder paste usage stencil_thickness: 0.12 - # [string='full'] Name for one of the internal templates (full, full_svg, simple) or a custom template file. + # [string='full'] [full,full_svg,simple,testpoints,*] Name for one of the internal templates or a custom template file. # Environment variables and ~ are allowed. - # Note: when converting to PDF PanDoc can fail on some Unicode values (use `simple_ASCII`) + # Note: when converting to PDF PanDoc can fail on some Unicode values (use `simple_ASCII`). + # Note: the testpoint variables uses the `testpoint` fabrication attribute of pads template: 'full' # [string=''] Board variant to apply variant: '' diff --git a/docs/source/Changelog.rst b/docs/source/Changelog.rst index 69ae2958..7f11dfef 100644 --- a/docs/source/Changelog.rst +++ b/docs/source/Changelog.rst @@ -56,6 +56,7 @@ Added - Solder paste usage stats (#616) - Support for variants (See #616) + - Testpoints report (See #638) - xDRC: configurable category (#647) - Schematic: @@ -66,6 +67,10 @@ Added - Support for KiCad 8 bitmaps (#623) +- Position: + + - Support for panels repeating the same component (See #656) + Fixed: ~~~~~~ diff --git a/docs/source/configuration/filters/expand_text_vars.rst b/docs/source/configuration/filters/expand_text_vars.rst index 39dce83c..824c7de7 100644 --- a/docs/source/configuration/filters/expand_text_vars.rst +++ b/docs/source/configuration/filters/expand_text_vars.rst @@ -8,8 +8,8 @@ Expand Text Variables This filter expands KiCad 6 text variables (${VARIABLE}). - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``include_kicad_env`` :index:`: ` [:ref:`boolean `] (default: ``true``) Also expand KiCad environment variables. - ``include_os_env`` :index:`: ` [:ref:`boolean `] (default: ``false``) Also expand system environment variables. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. diff --git a/docs/source/configuration/filters/field_modify.rst b/docs/source/configuration/filters/field_modify.rst index 166e722b..77c49ad1 100644 --- a/docs/source/configuration/filters/field_modify.rst +++ b/docs/source/configuration/filters/field_modify.rst @@ -8,13 +8,13 @@ Field Modifier Changes the content of one or more fields. - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``fields`` :index:`: ` [:ref:`string ` | :ref:`list(string) `] (default: ``'Datasheet'``) [:ref:`comma separated `] Fields to convert. - ``include`` :index:`: ` [:ref:`string ` | :ref:`list(string) `] (default: ``''``) Name of the filter to select which components will be affected. Applied to all if nothing specified here. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``regex`` :index:`: ` [:ref:`string `] (default: ``'(https?://\\S+)'``) Regular expression to match the field content. Only fields that matches will be modified. An empty regex will match anything. diff --git a/docs/source/configuration/filters/field_rename.rst b/docs/source/configuration/filters/field_rename.rst index 746725df..9c9547a5 100644 --- a/docs/source/configuration/filters/field_rename.rst +++ b/docs/source/configuration/filters/field_rename.rst @@ -9,8 +9,8 @@ Field Renamer This filter implements a field renamer. |br| The internal `_kicost_rename` filter emulates the KiCost behavior. |br| - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``rename`` :index:`: ` [:ref:`FieldRename parameters `] [:ref:`list(dict) `] (default: ``[]``) Fields to rename. .. toctree:: diff --git a/docs/source/configuration/filters/generic.rst b/docs/source/configuration/filters/generic.rst index 203c300a..a7cf88cf 100644 --- a/docs/source/configuration/filters/generic.rst +++ b/docs/source/configuration/filters/generic.rst @@ -12,7 +12,8 @@ Generic filter The internal `_mechanical` filter emulates the KiBoM behavior for default exclusions. |br| The internal `_kicost_dnp` filter emulates KiCost's `dnp` field. |br| - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``config_field`` :index:`: ` [:ref:`string `] (default: ``'Config'``) Name of the field used to classify components. - ``config_separators`` :index:`: ` [:ref:`string `] (default: ``' ,'``) Characters used to separate options inside the config field. - ``exclude_all_hash_ref`` :index:`: ` [:ref:`boolean `] (default: ``false``) Exclude all components with a reference starting with #. @@ -44,7 +45,6 @@ Generic filter Use `dnf_list` for ['dnf', 'dnl', 'dnp', 'do not fit', 'do not load', 'do not place', 'no stuff', 'nofit', 'noload', 'noplace', 'nostuff', 'not fitted', 'not loaded', 'not placed']. Use `dnc_list` for ['dnc', 'do not change', 'fixed', 'no change']. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. .. toctree:: :caption: Used dicts diff --git a/docs/source/configuration/filters/rot_footprint.rst b/docs/source/configuration/filters/rot_footprint.rst index b6a6b283..1bd7e4f1 100644 --- a/docs/source/configuration/filters/rot_footprint.rst +++ b/docs/source/configuration/filters/rot_footprint.rst @@ -11,6 +11,8 @@ Footprint Rotator The `JLCPCB Rotation Offset` and `JLCPCB Position Offset` fields can be used to adjust special cases. |br| The internal `_rot_footprint` filter implements the simplest case. |br| + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``bennymeg_mode`` :index:`: ` [:ref:`boolean `] (default: ``true``) Implements the `rot_fields` and `offset_fields` in the same way that the bennymeg/JLC-Plugin-for-KiCad tool. Note that the computation for bottom rotations is wrong, forcing the user to uses arbitrary rotations. The correct computation is `(180 - component rot) + angle` but the plugin does `180 - (component rot + angle)`. @@ -18,7 +20,6 @@ Footprint Rotator This option also controls the way offset signs are interpreted. When enabled the offsets matches this plugin, when disabled matches the interpretation used by the matthewlai/JLCKicadTools plugin. Disabling this option you'll get better algorithms, but loose compatibility with this plugin. - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. - ``extend`` :index:`: ` [:ref:`boolean `] (default: ``true``) Extends the internal list of rotations with the one provided. Otherwise just use the provided list. Note that the provided list has more precedence than the internal list. @@ -26,7 +27,6 @@ Footprint Rotator or when combined with `negative_bottom`, `(angle - component rot)`. - ``mirror_bottom`` :index:`: ` [:ref:`boolean `] (default: ``false``) The original component rotation for components in the bottom is mirrored before applying the adjust so you get `(180 - component rot + angle)`. This is used by JLCPCB. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``negative_bottom`` :index:`: ` [:ref:`boolean `] (default: ``true``) Rotation for bottom components is computed via subtraction as `(component rot - angle)`. - ``offset_fields`` :index:`: ` [:ref:`string ` | :ref:`list(string) `] (default: ``['JLCPCB Position Offset', 'JLCPosOffset']``) [:ref:`comma separated `] List of fields that can contain a position offset. The optional fields can contain a comma separated x,y position offset. diff --git a/docs/source/configuration/filters/separate_pins.rst b/docs/source/configuration/filters/separate_pins.rst index b0d15c80..a09afc2a 100644 --- a/docs/source/configuration/filters/separate_pins.rst +++ b/docs/source/configuration/filters/separate_pins.rst @@ -17,11 +17,11 @@ Separate Pins Needs KiCad 6 or newer. |br| .. + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``attribute`` :index:`: ` [:ref:`string ` | :ref:`list(string) `] (default: ``['testpoint']``) (choices: "bga", "local_fiducial", "global_fiducial", "testpoint", "heatsink", "castellated", "none") Fabrication attribute/s of the included pads. - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. - ``keep_component`` :index:`: ` [:ref:`boolean `] (default: ``false``) If we also keep the original component or we just get the selected pads. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``ref_sep`` :index:`: ` [:ref:`string `] (default: ``'.'``) Separator used in the reference (i.e. R10.1). diff --git a/docs/source/configuration/filters/spec_to_field.rst b/docs/source/configuration/filters/spec_to_field.rst index 8f72a0be..fc8c6440 100644 --- a/docs/source/configuration/filters/spec_to_field.rst +++ b/docs/source/configuration/filters/spec_to_field.rst @@ -13,15 +13,15 @@ Spec to Field the `bom` output. Make sure you can do this before trying to use this filter. |br| Usage `example `__. |br| + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. - **from_output** :index:`: ` [:ref:`string `] (default: ``''``) Name of the output used to collect the specs. Currently this must be a `bom` output with KiCost enabled and a distributor that returns specs. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - **specs** :index:`: ` [:ref:`SpecOptions parameters `] [:ref:`list(dict) ` | :ref:`dict `] (default: ``[{'spec': '_voltage', 'field': '_field_voltage'}, {'spec': '_tolerance', 'field': '_field_tolerance'}, {'spec': '_power', 'field': '_field_power'}, {'spec': '_current', 'field': '_field_current'}]``) One or more specs to be copied. - ``check_dist_coherence`` :index:`: ` [:ref:`boolean `] (default: ``true``) Check that the data we got from different distributors is equivalent. - ``check_dist_fields`` :index:`: ` [:ref:`string ` | :ref:`list(string) `] (default: ``['_value', '_tolerance', '_power', '_current', '_voltage', '_temp_coeff']``) [:ref:`comma separated `] List of fields to include in the check. For a full list of fields consult the `specs` option. - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. .. toctree:: :caption: Used dicts diff --git a/docs/source/configuration/filters/subparts.rst b/docs/source/configuration/filters/subparts.rst index 477ea0f2..fa3a9494 100644 --- a/docs/source/configuration/filters/subparts.rst +++ b/docs/source/configuration/filters/subparts.rst @@ -11,17 +11,17 @@ Subparts Some people use it to include connectors and cables related to a connector in the PCB. |br| `KiCost docs `__. |br| + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``check_multiplier`` :index:`: ` [:ref:`list(string) `] (default: computed for your project) List of fields to include for multiplier computation. If empty all fields in `split_fields` and `manf_pn_field` are used. - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. - ``manf_field`` :index:`: ` [:ref:`string `] (default: ``'manf'``) Field for the manufacturer name. - ``manf_pn_field`` :index:`: ` [:ref:`string `] (default: ``'manf#'``) Field for the manufacturer part number. - ``modify_first_value`` :index:`: ` [:ref:`boolean `] (default: ``true``) Modify even the value for the first component in the list (KiCost behavior). - ``modify_value`` :index:`: ` [:ref:`boolean `] (default: ``true``) Add '- p N/M' to the value. - ``mult_separators`` :index:`: ` [:ref:`string `] (default: ``':'``) Separators used for the multiplier. Each character in this string is a valid separator. - ``multiplier`` :index:`: ` [:ref:`boolean `] (default: ``true``) Enables the subpart multiplier mechanism. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``ref_sep`` :index:`: ` [:ref:`string `] (default: ``'#'``) Separator used in the reference (i.e. R10#1). - ``separators`` :index:`: ` [:ref:`string `] (default: ``';,'``) Separators used between subparts. Each character in this string is a valid separator. - ``split_fields`` :index:`: ` [:ref:`list(string) `] (default: ``['arrow#', 'digikey#', 'farnell#', 'lcsc#', 'mouser#', 'newark#', 'rs#', 'tme#']``) List of fields to split, usually the distributors part numbers. diff --git a/docs/source/configuration/filters/urlify.rst b/docs/source/configuration/filters/urlify.rst index c722f7f4..5f3b8a84 100644 --- a/docs/source/configuration/filters/urlify.rst +++ b/docs/source/configuration/filters/urlify.rst @@ -8,8 +8,8 @@ URLify Converts URL text in fields to HTML URLs. - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``fields`` :index:`: ` [:ref:`string ` | :ref:`list(string) `] (default: ``'Datasheet'``) [:ref:`comma separated `] Fields to convert. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. diff --git a/docs/source/configuration/filters/value_split.rst b/docs/source/configuration/filters/value_split.rst index e7581e35..e05a779e 100644 --- a/docs/source/configuration/filters/value_split.rst +++ b/docs/source/configuration/filters/value_split.rst @@ -10,10 +10,10 @@ Value Splitter I.e. extracts the tolerance and puts it in the `tolerance` field. |br| Usage `example `__. |br| + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``autoplace`` :index:`: ` [:ref:`boolean `] (default: ``true``) Try to figure out the position for the added fields. - ``autoplace_mechanism`` :index:`: ` [:ref:`string `] (default: ``'bottom'``) (choices: "bottom", "top") Put the new field at the bottom/top of the last field. - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``package`` :index:`: ` [:ref:`string `] (default: ``'yes'``) (choices: "yes", "no", "soft") Policy for the package. yes = overwrite existing value, no = don't touch, soft = copy if not defined. - ``power`` :index:`: ` [:ref:`string `] (default: ``'yes'``) (choices: "yes", "no", "soft") Policy for the power rating. diff --git a/docs/source/configuration/filters/var_rename.rst b/docs/source/configuration/filters/var_rename.rst index 97d0473e..6c493503 100644 --- a/docs/source/configuration/filters/var_rename.rst +++ b/docs/source/configuration/filters/var_rename.rst @@ -13,9 +13,9 @@ Variant Renamer with *Diode_SMD:D_0805_2012Metric* will change the footprint when *VARIANT* is in use. Of course the footprints should be similar, or your PCB will become invalid. |br| - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``force_variant`` :index:`: ` [:ref:`string `] (default: ``''``) Use this variant instead of the current variant. Useful for IBoM variants. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``separator`` :index:`: ` [:ref:`string `] (default: ``':'``) Separator used between the variant and the field name. - ``variant_to_value`` :index:`: ` [:ref:`boolean `] (default: ``false``) Rename fields matching the variant to the value of the component. diff --git a/docs/source/configuration/filters/var_rename_kicost.rst b/docs/source/configuration/filters/var_rename_kicost.rst index bc8a0501..b7c49137 100644 --- a/docs/source/configuration/filters/var_rename_kicost.rst +++ b/docs/source/configuration/filters/var_rename_kicost.rst @@ -17,8 +17,8 @@ Variant Renamer KiCost style other filters to fine-tune the behavior, i.e. you can make the mechanism to be triggered by fields like *kibot.VARIANT|FIELD*. |br| - - ``comment`` :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. - - ``name`` :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. + - **comment** :index:`: ` [:ref:`string `] (default: ``''``) A comment for documentation purposes. + - **name** :index:`: ` [:ref:`string `] (default: ``''``) Used to identify this particular filter definition. - ``prefix`` :index:`: ` [:ref:`string `] (default: ``'kicost.'``) A mandatory prefix. Is not case sensitive. - ``separator`` :index:`: ` [:ref:`string `] (default: ``':'``) Separator used between the variant and the field name. - ``variant`` :index:`: ` [:ref:`string `] (default: ``''``) Variant regex to match the VARIANT part. diff --git a/docs/source/configuration/outputs/ReportOptions.rst b/docs/source/configuration/outputs/ReportOptions.rst index 795ae89a..15e06a67 100644 --- a/docs/source/configuration/outputs/ReportOptions.rst +++ b/docs/source/configuration/outputs/ReportOptions.rst @@ -12,9 +12,10 @@ ReportOptions parameters In CI/CD environments: the `kicad_auto_test` docker image contains it. In Debian/Ubuntu environments: install `pandoc`, `texlive`, `texlive-latex-base` and `texlive-latex-recommended`. - **output** :index:`: ` [:ref:`string `] (default: ``'%f-%i%I%v.%x'``) Output file name (%i='report', %x='txt'). Affected by global options. -- **template** :index:`: ` [:ref:`string `] (default: ``'full'``) Name for one of the internal templates (full, full_svg, simple) or a custom template file. +- **template** :index:`: ` [:ref:`string `] (default: ``'full'``) (choices: "full", "full_svg", "simple", "testpoints") (also accepts any string) Name for one of the internal templates or a custom template file. Environment variables and ~ are allowed. Note: when converting to PDF PanDoc can fail on some Unicode values (use `simple_ASCII`). + Note: the testpoint variables uses the `testpoint` fabrication attribute of pads. - ``alloy_specific_gravity`` :index:`: ` [:ref:`number `] (default: ``7.4``) Specific gravity of the alloy used for the solder paste, in g/cm3. Used to compute solder paste usage. - ``convert_from`` :index:`: ` [:ref:`string `] (default: ``'markdown'``) Original format for the report conversion. Current templates are `markdown`. See `do_convert`. - ``converted_output`` :index:`: ` [:ref:`string `] (default: ``'%f-%i%I%v.%x'``) Converted output file name (%i='report', %x=`convert_to`).