diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cli.rst | 135 | ||||
| -rw-r--r-- | docs/file-api.rst | 7 | ||||
| -rw-r--r-- | docs/index.rst | 15 |
3 files changed, 152 insertions, 5 deletions
diff --git a/docs/cli.rst b/docs/cli.rst new file mode 100644 index 0000000..e64d11c --- /dev/null +++ b/docs/cli.rst @@ -0,0 +1,135 @@ +.. _cli-doc: + +Gerbonara's Command-Line Interface +================================== + +Gerbonara comes with a built-in command-line interface that has functions for analyzing, rendering, modifying, and +merging Gerber files. + +Invocation +---------- + +There are two ways to call gerbonara's command-line interface: + +.. :code: + + $ gerbonara + $ python -m gerbonara + +For the first to work, make sure the installation's ``bin`` dir is in your ``$PATH``. If you installed gerbonara +system-wide, that should be the case already, since the binary should end up in ``/usr/bin``. If you installed gerbonara +using ``pip install --user``, make sure you have your user's ``~/.local/bin`` in your ``$PATH``. + +Commands and their usage +------------------------ + +.. code-block:: console + + $ gerbonara --help + Usage: gerbonara [OPTIONS] COMMAND [ARGS]... + + The gerbonara CLI allows you to analyze, render, modify and merge both + individual Gerber or Excellon files as well as sets of those files + + Options: + --version + --help Show this message and exit. + + Commands: + bounding-box Print the bounding box of a gerber file in "[x_min]... + layers Read layers from a directory or zip with Gerber files and... + merge Merge multiple single Gerber or Excellon files, or... + meta Extract layer mapping and print it along with layer... + render Render a gerber file, or a directory or zip of gerber... + rewrite Parse a single gerber file, apply transformations, and... + transform Transform all gerber files in a given directory or zip... + +Rendering +~~~~~~~~~ + +Gerbonara can render single Gerber (:py:class:`~.rs274x.GerberFile`) or Excellon (:py:class:`~.excellon.ExcellonFile`) +layers, or whole board stacks (:py:class:`~.layers.LayerStack`) to SVG. + +``gerbonara render`` +******************** +.. program:: gerbonara render + +.. code-block:: console + + $ gerbonara render [OPTIONS] INPATH [OUTFILE] + +``gerbonara render`` renders one or more Gerber or Excellon files as a single SVG file. It can read single files, +directorys of files, and ZIP files. To read directories or zips, it applies gerbonara's layer filename matching rules. + +.. option:: --warnings [default|ignore|once] + + Enable or disable file format warnings during parsing (default: on) + + +.. 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 :option:`--input-map` + + +.. option:: --force-zip + + Force treating input path as a zip file (default: guess file type from extension and contents) + +.. option:: --top, --bottom + + Which side of the board to render + +.. option:: --command-line-units <metric|us-customary> + + Units for values given in other options. Default: millimeter + +.. option:: --margin <float> + + Add space around the board inside the viewport + +.. option:: --force-bounds <min_x,min_y,max_x,max_y> + + Force SVG bounding box to the given value. + +.. option:: --inkscape, --standard-svg + + Export in Inkscape SVG format with layers and stuff instead of plain SVG. + +.. option:: --colorscheme <json_file> + + Load colorscheme from given JSON file. The JSON file must contain a single dict with keys ``copper``, ``silk``, + ``mask``, ``paste``, ``drill`` and ``outline``. Each key must map to a string containing either a normal 6-digit hex + color with leading hash sign, or an 8-digit hex color with leading hash sign, where the last two digits set the + layer's alpha value (opacity), with ``ff`` being completely opaque, and ``00`` being invisibly transparent. + +Modification +~~~~~~~~~~~~ + +``gerbonara rewrite`` +********************* + +``gerbonara transform`` +*********************** + +``gerbonara merge`` +******************* + +File analysis +~~~~~~~~~~~~~ + +``gerbonara bounding-box`` +************************** + +``gerbonara meta`` +****************** + +``gerbonara layers`` +******************** + diff --git a/docs/file-api.rst b/docs/file-api.rst index ba472d4..becd63f 100644 --- a/docs/file-api.rst +++ b/docs/file-api.rst @@ -12,10 +12,6 @@ syntactic hints, and can automatically match all files in a folder to their appr :py:class:`.CamFile` is the common base class for all layer types. - -.. autoclass:: gerbonara.layers.LayerStack - :members: - .. autoclass:: gerbonara.cam.CamFile :members: @@ -28,3 +24,6 @@ syntactic hints, and can automatically match all files in a folder to their appr .. autoclass:: gerbonara.ipc356.Netlist :members: +.. autoclass:: gerbonara.layers.LayerStack + :members: + diff --git a/docs/index.rst b/docs/index.rst index ab363c6..45dbc1b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,6 +46,7 @@ Features :maxdepth: 2 :caption: Contents: + cli api-concepts file-api object-api @@ -73,6 +74,18 @@ Then, you are ready to read and write gerber files: w, h = stack.outline.size('mm') print(f'Board size is {w:.1f} mm x {h:.1f} mm') +Command-Line Interface +====================== + +Gerbonara comes with a :ref:`built-in command-line interface<cli-doc>` that has functions for analyzing, rendering, +modifying, and merging Gerber files. To access it, use either the ``gerbonara`` command that is part of the python +package, or run ``python -m gerbonara``. For a list of functions or help on their usage, you can use: + +.. code:: console + + $ python -m gerbonara --help + [...] + $ python -m gerbonara render --help Development =========== @@ -93,7 +106,7 @@ A copy of this documentation can also be found at gitlab: https://gerbolyze.gitlab.io/gerbonara/ -With Gebronara, we aim to support as many different format variants as possible. If you have a file that Gerbonara can't +With Gerbonara, we aim to support as many different format variants as possible. If you have a file that Gerbonara can't open, please file an issue on our issue tracker. Even if Gerbonara can open all your files, for regression testing we are very interested in example files generated by any CAD or CAM tool that is not already on the list of supported tools. |