Still more doc

1 files changed, 237 insertions, 0 deletions

diff --git a/docs/cli.rst b/docs/cli.rst
index e64d11c..8eb1ff3 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -115,21 +115,258 @@ Modification
 ``gerbonara rewrite``
 *********************
 
+.. program:: gerbonara rewrite
+
+.. code-block:: console
+   
+    gerbonara rewrite [OPTIONS] INFILE OUTFILE
+
+Parse a single gerber file, apply transformations, and re-serialize it into a new gerber file. Without transformations,
+this command can be used to convert a gerber file to use different settings (e.g. units, precision), but can also be
+used to "normalize" gerber files in a weird format into a more standards-compatible one as gerbonara's gerber parser is
+significantly more robust for weird inputs than others.
+
+.. option:: --warnings <default|ignore|once>
+
+   Enable or disable file format warnings during parsing (default: on)
+
+.. option:: -t, --transform <code>
+
+   Execute python transformation script on input. You have access to the functions ``translate(x, y)``,
+   ``scale(factor)`` and ``rotate(angle, center_x?, center_y?)``, the bounding box variables ``x_min``, ``y_min``,
+   ``x_max``, ``y_max``, ``width`` and ``height``, and everything from python's built-in math module (e.g. ``pi``,
+   ``sqrt``, ``sin``). As convenience methods, ``center()`` and ``origin()`` are provided to center the board
+   respectively move its bottom-left corner to the origin. Coordinates are given in ``--command-line-units``, angles in
+   degrees, and scale as a scale factor (as opposed to a percentage). Example: ``translate(-10, 0); rotate(45, 0, 5)``
+
+.. option:: --command-line-units <metric|us-customary>
+
+    Units for values given in other options. Default: millimeter
+
+.. option:: -n, --number-format <decimal.fractional>
+
+   Override number format to use during export in ``[integer digits].[decimal digits]`` notation, e.g. ``2.6``.
+
+.. option:: -u, --units <metric|us-customary>
+
+   Override export file units
+
+.. option:: -z, --zero-suppression <off|leading|trailing>
+
+   Override export zero suppression setting. Note: The meaning of this value is like in the Gerber spec for both Gerber
+   and Excellon files!
+
+.. option:: --keep-comments, --drop-comments
+
+   Keep gerber comments. Note: Comments will be prepended to the start of file, and will not occur in their old
+   position.
+
+.. option:: --default-settings, --reuse-input-settings
+
+   Use sensible defaults for the output file format settings (default) or use the same export settings as the input file
+   instead of sensible defaults.
+
+.. option:: --input-number-format <decimal.fractional>
+
+   Override number format of input file (mostly useful for Excellon files)
+
+.. option:: --input-units <metric|us-customary>
+
+   Override units of input file
+
+.. option:: --input-zero-suppression <off|leading|trailing>
+
+   Override zero suppression setting of input file
+
+
 ``gerbonara transform``
 ***********************
 
+.. program:: gerbonara transform
+
+.. code-block:: console
+
+    gerbonara transform [OPTIONS] TRANSFORM INPATH OUTPATH
+
+Transform all gerber files in a given directory or zip file using the given python transformation script.
+
+In the python transformation script you have access to the functions ``translate(x, y)``, ``scale(factor)`` and
+``rotate(angle, center_x?, center_y?)``, the bounding box variables ``x_min``, ``y_min``, ``x_max``, ``y_max``,
+``width`` and ``height``, and everything from python's built-in math module (e.g. ``pi``, ``sqrt``, ``sin``). As
+convenience methods, ``center()`` and ``origin()`` are provided to center the board resp. move its bottom-left corner to
+the origin. Coordinates are given in --command-line-units, angles in degrees, and scale as a scale factor (as opposed to
+a percentage). Example: ``translate(-10, 0); rotate(45, 0, 5)``
+
+.. option:: -m, --input-map <json_file>
+
+   Extend or override layer name mapping with name map from JSON file. The JSON file must contain a single JSON dict
+   with an arbitrary number of string: string entries. The keys are interpreted as regexes applied to the filenames via
+   re.fullmatch, and each value must either be the string ``ignore`` to remove this layer from previous automatic
+   guesses, or a gerbonara layer name such as ``top copper``, ``inner_2 copper`` or ``bottom silk``.
+
+.. option:: --use-builtin-name-rules, --no-builtin-name-rules
+
+    Disable built-in layer name rules and use only rules given by ``--input-map``
+
+.. option:: --warnings <default|ignore|once>
+
+   Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --units <metric|us-customary>
+
+    Units for values given in other options. Default: millimeter
+
+.. option:: -n, --number-format <decimal.fractional>
+
+   Override number format to use during export in ``[integer digits].[decimal digits]`` notation, e.g. ``2.6``.
+
+.. option:: --default-settings, --reuse-input-settings
+
+   Use sensible defaults for the output file format settings (default) or use the same export settings as the input file
+   instead of sensible defaults.
+
+.. option:: --force-zip
+
+   Force treating input path as a zip file (default: guess file type from extension and contents)
+
+.. option:: --output-naming-scheme <altium|kicad>
+
+   Name output files according to the selected naming scheme instead of keeping the old file names.
+
+
 ``gerbonara merge``
 *******************
 
+.. program:: gerbonara merge
+
+.. code-block:: console
+   
+    $ gerbonara merge [OPTIONS] [INPATH]... OUTPATH
+
+Merge multiple single Gerber or Excellon files, or multiple stacks of Gerber files, into one.
+
+.. note::
+   When used with only one input, this command *normalizes* the input, converting all files to a well-defined, widely
+   supported Gerber subset with sane settings. When a ``--output-naming-scheme`` is given, it additionally renames all
+   files to a standardized naming convention.
+
+.. option:: --command-line-units <metric|us-customary>
+
+    Units for values given in --transform. Default: millimeter
+
+.. option:: --warnings <default|ignore|once>
+
+   Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --offset <COORDINATE>
+
+   Offset for the n'th file as a ``x,y`` string in unit given by ``--command-line-units`` (default: millimeter). Can be
+   given multiple times, and the first option affects the first input, the second option affects the second input, and
+   so on.
+
+.. option:: --rotation <ROTATION>
+
+   Rotation for the n'th file in degrees clockwise, optionally followed by comma- separated rotation center X and Y
+   coordinates. Can be given multiple times, and the first option affects the first input, the second option affects the
+   second input, and so on.
+
+.. option:: -m, --input-map <json_file>
+
+   Extend or override layer name mapping with name map from JSON file. This option can be given multiple times, in which
+   case the n'th option affects only the n'th input, like with ``--offset`` and ``--rotation``. The JSON file must
+   contain a single JSON dict with an arbitrary number of string: string entries. The keys are interpreted as regexes
+   applied to the filenames via re.fullmatch, and each value must either be the string "ignore" to remove this layer
+   from previous automatic guesses, or a gerbonara layer name such as ``top copper``, ``inner_2 copper`` or ``bottom
+   silk``.
+
+.. option:: --default-settings, --reuse-input-settings
+
+   Use sensible defaults for the output file format settings (default) or use the same export settings as the input file
+   instead of sensible defaults.
+
+.. option:: --output-naming-scheme <altium|kicad>
+
+   Name output files according to the selected naming scheme instead of keeping the old file names of the first input.
+
+.. option:: --output-board-name <TEXT>
+
+    Override board name used with ``--output-naming-scheme``
+
+.. option:: --use-builtin-name-rules, --no-builtin-name-rules
+    
+    Disable built-in layer name rules and use only rules given by --input-map
+
 File analysis
 ~~~~~~~~~~~~~
 
 ``gerbonara bounding-box``
 **************************
 
+.. program:: gerbonara bounding-box
+
+.. code-block:: console
+
+   gerbonara bounding-box [OPTIONS] INFILE
+
+Print the bounding box of a gerber file in ``[x_min] [y_min] [x_max] [y_max]`` format. The bounding box contains all
+graphic objects in this file, so e.g. a 100 mm by 100 mm square drawn with a 1mm width circular aperture will result in
+an 101 mm by 101 mm bounding box.
+
+.. option:: --warnings <default|ignore|once>
+
+    Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --units <metric|us-customary>
+    
+    Output bounding box in this unit (default: millimeter)
+
+.. option:: --input-number-format <decimal.fractional>
+
+    Override number format of input file (mostly useful for Excellon files)
+    
+.. option:: --input-units <metric|us-customary>
+
+    Override units of input file
+
+.. option:: --input-zero-suppression <off|leading|trailing>
+
+    Override zero suppression setting of input file
+
+
 ``gerbonara meta``
 ******************
+.. program:: gerbonara meta
+
+.. code-block:: console
+
+    gerbonara meta [OPTIONS] PATH
+
+Read a board from a folder or zip, and print the found layer mapping along with layer metadata as JSON to stdout. A
+machine-readable variant of the :program:`gerbonara render` command. All lengths in the JSON are given in millimeter.
+
+.. option:: --warnings <default|ignore|once>
+
+   Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --force-zip
+
+   Force treating input path as zip file (default: guess file type from extension and contents)
+
 
 ``gerbonara layers``
 ********************
+.. program:: gerbonara render
+
+.. code-block:: console
+
+    $ gerbonara layers [OPTIONS] PATH
+
+Prints a layer-by-layer description of the board found under the given path. The path can be a directory or zip file.
+
+.. option:: --warnings <default|ignore|once>
+
+   Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --force-zip
 
+   Force treating input path as zip file (default: guess file type from extension and contents)