1 files changed, 141 insertions, 0 deletions
diff --git a/content/projects/gerbonara/index.rst b/content/projects/gerbonara/index.rst
new file mode 100644
index 0000000..be28fb4
--- /dev/null
+++ b/content/projects/gerbonara/index.rst
@@ -0,0 +1,141 @@
+---
+title: "Gerbonara"
+external_links:
+    - name: Sources
+      url: "https://git.jaseg.de/gerbonara.git"
+    - name: Issues
+      url: "https://gitlab.com/gerbolyze/gerbonara/issues"
+    - name: Docs
+      url: "https://gerbolyze.gitlab.io/gerbonara"
+    - name: PyPI
+      url: "https://pypi.org/projects/gerbonara"
+summary: >
+    Gerbonara is a user-friendly, powerful tool for reading, writing, modification and rendering of Gerber PCB artwork
+    from the command line or from Python code. Gerbonara supports the Gerber dialects of all industry-standard EDA
+    tools.
+---
+
+Gerbonara is a library to read, modify and write PCB manufacturing files such as Gerber, Excellon and IPC-356 through a
+pythonic API. Gerbonara can open a folder of manufacturing files, and parse file names and metadata to figure out which
+file contains what. Gerbonara is tested using an extensive library of real-world example files from CAD tools including
+KiCAD, Altium, Eagle, Allegro, gEDA, Fritzing, Siemens/Mentor Graphics PADS, and Target3001!.
+
+Gerbonara's API is built on two principles:
+
+**Meaningful, object-oriented API**
+    Gerbonara abstracts away the details of the underlying file format such as tool indices, coordinate notation and
+    graphical state, and presents meaningful "graphical objects" such as a `primitives.Line`,
+    `primitives.Arc`, or `Region` through its API. These objects can be easily created,
+    manipulated or deleted from code without breaking anything else. You can even copy graphical objects between files,
+    and Gerbonara will automatically convert coordinate format, units etc. for you. `GerberFile` and
+    `ExcellonFile` use the same types of `graphic objects <object-api>`, so objects can be directly
+    copied between file types without conversion.
+
+**Unit-safety**
+    Gerbonara embeds physical `LengthUnit` information in all objects. The high-level API such as
+    `LayerStack.merge` or `GerberFile.offset` accepts arguments with an explicitly given unit and
+    automatically converts them as needed. Objects can be copied between `GerberFile` instances and unit
+    conversion will be handled transparently in the background.
+
+Gerbonara was started as an extensive refactoring of the pcb-tools_ and pcb-tools-extension_ packages. Both of these
+have statement-based APIs, that is, they parse input files into one python object for every line in the file. This means
+that when saving files they can recreate the input file almost byte by byte, but manipulating a file by changing
+statements without breaking things is *hard*.
+
+Gerbonara powers gerbolyze_, a tool for converting SVG_ vector graphics files into Gerber, and embedding SVG_ into
+existing Gerber files exported from a normal PCB tool for artistic purposes.
+
+Features
+========
+
+ * File I/O
+   * Gerber, Excellon (drill file), IPC-356 (netlist) read and write
+   * supports file-level operations: offset, rotate, merge for all file types
+ * Modification API (`GraphicObject`)
+ * Rendering API (`GraphicPrimitive`)
+ * SVG export
+ * Full aperture macro support, including transformations (offset, rotation)
+
+Quick Start
+===========
+
+First, install gerbonara from PyPI using pip:
+
+.. code-block:: shell
+
+   pip install --user gerbonara
+
+Then, you are ready to read and write gerber files:
+
+.. code-block:: python
+
+    from gerbonara import LayerStack
+
+    stack = LayerStack.from_directory('output/gerber')
+    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 `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
+===========
+
+Gerbonara is developed on Gitlab under the gerbolyze org:
+
+https://gitlab.com/gerbolyze/gerbonara/
+
+A mirror of the repository can be found at:
+
+https://git.jaseg.de/gerbonara
+
+Our issue tracker is also on Gitlab:
+
+https://gitlab.com/gerbolyze/gerbonara/-/issues
+
+The documentation can be found at gitlab:
+
+https://gerbolyze.gitlab.io/gerbonara/
+
+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.
+
+Supported CAD Tools
+===================
+
+Compatibility with the output of these CAD tools is tested as part of our test suite using example files generated by
+these tools. Note that not all of these tools come with default Gerber file naming rules, so YMMV if your Gerbers use
+some non-standard naming convention.
+
+ * Allegro
+ * Altium
+ * Diptrace
+ * Eagle
+ * EasyEDA
+ * Fritzing
+ * gEDA
+ * KiCAD
+ * pcb-rnd
+ * Siemens / Mentor Graphics Xpedition
+ * Siemens PADS
+ * Target 3001!
+ * Upverter
+ * Zuken CR-8000
+
+.. _pcb-tools: https://github.com/opiopan/pcb-tools-extension
+.. _pcb-tools-extension: https://github.com/curtacircuitos/pcb-tools/issues
+.. _gerbolyze: https://github.com/jaseg/gerbolyze
+.. _SVG: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
+