Add some documentation

1 files changed, 115 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..55d2456
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,115 @@
+Welcome to gerbonara's documentation!
+=====================================
+
+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 :py:class:`~primitives.Line`,
+    :py:class:`~primitives.Arc`, or :py:class:`.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. :py:class:`.GerberFile` and
+    :py:class:`.ExcellonFile` use the same types of :doc:`graphic objects <object-api>`, so objects can be directly
+    copied between file types without conversion.
+
+**Unit-safety**
+    Gerbonara embeds physical :py:class:`.LengthUnit` information in all objects. The high-level API such as
+    :py:meth:`.LayerStack.merge` or :py:meth:`.GerberFile.offset` accepts arguments with an explicitly given unit and
+    automatically converts them as needed. Objects can be copied between :py:class:`.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 (:py:class:`GraphicObject`)
+ * Rendering API (:py:class:`GraphicPrimitive`)
+ * SVG export
+ * Full aperture macro support, including transformations (offset, rotation)
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    api-concepts
+    file-api
+    object-api
+    apertures
+    aperture-macros
+    graphic-primitive-api
+    utilities
+
+Quick Start
+===========
+
+
+
+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
+
+With Gebronara, 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 / Mentor Graphics PADS
+ * Target 3001!
+ * Upverter
+ * Soon: Zuken CADSTAR and CR-8000
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+.. _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
+