Add some documentation

28 files changed, 788 insertions, 941 deletions

diff --git a/.gitignore b/.gitignore
index 1829a16..f5927cd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@ gerbonara_test_failures
 *.egg-info
 __pycache__
 .tox
+docs/_build/
diff --git a/Makefile b/Makefile
index 966f2a0..c7a70a1 100644
--- a/Makefile
+++ b/Makefile
@@ -1,13 +1,21 @@
 
-PYTHON ?= python
-PYTEST ?= pytest
+PYTHON 			?= python
+PYTEST 			?= pytest
+SPHINX_BUILD	?= sphinx-build
+
+all: docs sdist bdist_wheel
 
 .PHONY: clean
-clean: doc-clean
+clean:
 	find . -name '*.pyc' -delete
 	rm -rf *.egg-info
 	rm -f .coverage
 	rm -f coverage.xml
+	rm -rf docs/_build
+
+.PHONY: docs
+docs:
+	sphinx-build -E docs docs/_build
 
 .PHONY: test
 test:
@@ -30,7 +38,7 @@ bdist_wheel:
 	python3 setup.py bdist_wheel
 
 upload: sdist bdist_wheel
-	twine upload -s -i contact@gerbonara.io --config-file ~/.pypirc --skip-existing --repository pypi dist/*
+	twine upload -s -i gerbonara@jaseg.de --config-file ~/.pypirc --skip-existing --repository pypi dist/*
 
 testupload: sdist bdist_wheel
 	twine upload --config-file ~/.pypirc --skip-existing --repository testpypi dist/*
diff --git a/doc/Makefile b/doc/Makefile
deleted file mode 100644
index 5c6b560..0000000
--- a/doc/Makefile
+++ /dev/null
@@ -1,177 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = build
-
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GerberTools.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GerberTools.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/GerberTools"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GerberTools"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/doc/make.bat b/doc/make.bat
deleted file mode 100644
index 2860659..0000000
--- a/doc/make.bat
+++ /dev/null
@@ -1,242 +0,0 @@
-@ECHO OFF

-

-REM Command file for Sphinx documentation

-

-if "%SPHINXBUILD%" == "" (

-	set SPHINXBUILD=sphinx-build

-)

-set BUILDDIR=build

-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source

-set I18NSPHINXOPTS=%SPHINXOPTS% source

-if NOT "%PAPER%" == "" (

-	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%

-	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%

-)

-

-if "%1" == "" goto help

-

-if "%1" == "help" (

-	:help

-	echo.Please use `make ^<target^>` where ^<target^> is one of

-	echo.  html       to make standalone HTML files

-	echo.  dirhtml    to make HTML files named index.html in directories

-	echo.  singlehtml to make a single large HTML file

-	echo.  pickle     to make pickle files

-	echo.  json       to make JSON files

-	echo.  htmlhelp   to make HTML files and a HTML help project

-	echo.  qthelp     to make HTML files and a qthelp project

-	echo.  devhelp    to make HTML files and a Devhelp project

-	echo.  epub       to make an epub

-	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter

-	echo.  text       to make text files

-	echo.  man        to make manual pages

-	echo.  texinfo    to make Texinfo files

-	echo.  gettext    to make PO message catalogs

-	echo.  changes    to make an overview over all changed/added/deprecated items

-	echo.  xml        to make Docutils-native XML files

-	echo.  pseudoxml  to make pseudoxml-XML files for display purposes

-	echo.  linkcheck  to check all external links for integrity

-	echo.  doctest    to run all doctests embedded in the documentation if enabled

-	goto end

-)

-

-if "%1" == "clean" (

-	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i

-	del /q /s %BUILDDIR%\*

-	goto end

-)

-

-

-%SPHINXBUILD% 2> nul

-if errorlevel 9009 (

-	echo.

-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx

-	echo.installed, then set the SPHINXBUILD environment variable to point

-	echo.to the full path of the 'sphinx-build' executable. Alternatively you

-	echo.may add the Sphinx directory to PATH.

-	echo.

-	echo.If you don't have Sphinx installed, grab it from

-	echo.http://sphinx-doc.org/

-	exit /b 1

-)

-

-if "%1" == "html" (

-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.

-	goto end

-)

-

-if "%1" == "dirhtml" (

-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.

-	goto end

-)

-

-if "%1" == "singlehtml" (

-	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.

-	goto end

-)

-

-if "%1" == "pickle" (

-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished; now you can process the pickle files.

-	goto end

-)

-

-if "%1" == "json" (

-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished; now you can process the JSON files.

-	goto end

-)

-

-if "%1" == "htmlhelp" (

-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished; now you can run HTML Help Workshop with the ^

-.hhp project file in %BUILDDIR%/htmlhelp.

-	goto end

-)

-

-if "%1" == "qthelp" (

-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished; now you can run "qcollectiongenerator" with the ^

-.qhcp project file in %BUILDDIR%/qthelp, like this:

-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\GerberTools.qhcp

-	echo.To view the help file:

-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\GerberTools.ghc

-	goto end

-)

-

-if "%1" == "devhelp" (

-	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished.

-	goto end

-)

-

-if "%1" == "epub" (

-	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The epub file is in %BUILDDIR%/epub.

-	goto end

-)

-

-if "%1" == "latex" (

-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.

-	goto end

-)

-

-if "%1" == "latexpdf" (

-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex

-	cd %BUILDDIR%/latex

-	make all-pdf

-	cd %BUILDDIR%/..

-	echo.

-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.

-	goto end

-)

-

-if "%1" == "latexpdfja" (

-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex

-	cd %BUILDDIR%/latex

-	make all-pdf-ja

-	cd %BUILDDIR%/..

-	echo.

-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.

-	goto end

-)

-

-if "%1" == "text" (

-	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The text files are in %BUILDDIR%/text.

-	goto end

-)

-

-if "%1" == "man" (

-	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The manual pages are in %BUILDDIR%/man.

-	goto end

-)

-

-if "%1" == "texinfo" (

-	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.

-	goto end

-)

-

-if "%1" == "gettext" (

-	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.

-	goto end

-)

-

-if "%1" == "changes" (

-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.The overview file is in %BUILDDIR%/changes.

-	goto end

-)

-

-if "%1" == "linkcheck" (

-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Link check complete; look for any errors in the above output ^

-or in %BUILDDIR%/linkcheck/output.txt.

-	goto end

-)

-

-if "%1" == "doctest" (

-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Testing of doctests in the sources finished, look at the ^

-results in %BUILDDIR%/doctest/output.txt.

-	goto end

-)

-

-if "%1" == "xml" (

-	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The XML files are in %BUILDDIR%/xml.

-	goto end

-)

-

-if "%1" == "pseudoxml" (

-	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml

-	if errorlevel 1 exit /b 1

-	echo.

-	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.

-	goto end

-)

-

-:end

diff --git a/doc/source/about.rst b/doc/source/about.rst
deleted file mode 100644
index 85e7184..0000000
--- a/doc/source/about.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-About PCB Tools
-===============
-
-
-PCB Tools provides a set of utilities for visualizing and working with PCB
-design files in a variety of formats. The design files are generally referred
-to as Gerber files. This is a generic term that may refer to
-`RS-274X (Gerber) <http://en.wikipedia.org/wiki/Gerber_format>`_,
-`ODB++ <http://en.wikipedia.org/wiki/ODB%2B%2B>`_ ,
-or `Excellon <http://en.wikipedia.org/wiki/Excellon_format>`_ files. These
-file formats are used by the CNC equipment used to manufacutre PCBs.
-
-PCB Tools currently supports the following file formats:
-
-- Gerber (RS-274X)
-- Excellon
-
-with planned support for IPC-2581, ODB++ and more.
-
-Image Rendering
-~~~~~~~~~~~~~~~
-.. image:: ../../examples/cairo_example.png
-   :alt: Rendering Example
-
-The PCB Tools module provides tools to visualize PCBs and export images in a
-variety of formats, including SVG and PNG.
-
-
-
-
-Future Plans
-~~~~~~~~~~~~
-We are working on adding the following features to PCB Tools:
-
-- Design Rules Checking
-- Editing
-- Panelization
-
-
-
diff --git a/doc/source/conf.py b/doc/source/conf.py
deleted file mode 100644
index 238a0b8..0000000
--- a/doc/source/conf.py
+++ /dev/null
@@ -1,262 +0,0 @@
-# -*- coding: utf-8 -*-

-#

-# Gerber Tools documentation build configuration file, created by

-# sphinx-quickstart on Sun Sep 28 18:16:46 2014.

-#

-# This file is execfile()d with the current directory set to its

-# containing dir.

-#

-# Note that not all possible configuration values are present in this

-# autogenerated file.

-#

-# All configuration values have a default; values that are commented out

-# serve to show the default.

-

-import sys

-import os

-

-# If extensions (or modules to document with autodoc) are in another directory,

-# add these directories to sys.path here. If the directory is relative to the

-# documentation root, use os.path.abspath to make it absolute, like shown here.

-sys.path.insert(0, os.path.abspath('../../'))

-

-# -- General configuration ------------------------------------------------

-

-# If your documentation needs a minimal Sphinx version, state it here.

-#needs_sphinx = '1.0'

-

-# Add any Sphinx extension module names here, as strings. They can be

-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

-# ones.

-extensions = [

-    'sphinx.ext.autodoc',

-    'sphinx.ext.autosummary',

-    'numpydoc',

-]

-

-# Add any paths that contain templates here, relative to this directory.

-templates_path = ['_templates']

-

-# The suffix of source filenames.

-source_suffix = '.rst'

-

-# The encoding of source files.

-#source_encoding = 'utf-8-sig'

-

-# The master toctree document.

-master_doc = 'index'

-

-# General information about the project.

-project = u'PCB Tools'

-copyright = u'2014 Paulo Henrique Silva <ph.silva@gmail.com>, Hamilton Kibbe <ham@hamiltonkib.be>'

-

-# The version info for the project you're documenting, acts as replacement for

-# |version| and |release|, also used in various other places throughout the

-# built documents.

-#

-# The short X.Y version.

-version = '0.1'

-# The full version, including alpha/beta/rc tags.

-release = '0.1'

-

-# The language for content autogenerated by Sphinx. Refer to documentation

-# for a list of supported languages.

-#language = None

-

-# There are two options for replacing |today|: either, you set today to some

-# non-false value, then it is used:

-#today = ''

-# Else, today_fmt is used as the format for a strftime call.

-#today_fmt = '%B %d, %Y'

-

-# List of patterns, relative to source directory, that match files and

-# directories to ignore when looking for source files.

-exclude_patterns = []

-

-# The reST default role (used for this markup: `text`) to use for all

-# documents.

-#default_role = None

-

-# If true, '()' will be appended to :func: etc. cross-reference text.

-#add_function_parentheses = True

-

-# If true, the current module name will be prepended to all description

-# unit titles (such as .. function::).

-add_module_names = False

-

-# If true, sectionauthor and moduleauthor directives will be shown in the

-# output. They are ignored by default.

-show_authors = False

-

-# The name of the Pygments (syntax highlighting) style to use.

-pygments_style = 'sphinx'

-

-# A list of ignored prefixes for module index sorting.

-#modindex_common_prefix = []

-

-# If true, keep warnings as "system message" paragraphs in the built documents.

-#keep_warnings = False

-

-

-# -- Options for HTML output ----------------------------------------------

-

-# The theme to use for HTML and HTML Help pages.  See the documentation for

-# a list of builtin themes.

-html_theme = 'default'

-

-# Theme options are theme-specific and customize the look and feel of a theme

-# further.  For a list of options available for each theme, see the

-# documentation.

-#html_theme_options = {}

-

-# Add any paths that contain custom themes here, relative to this directory.

-#html_theme_path = []

-

-# The name for this set of Sphinx documents.  If None, it defaults to

-# "<project> v<release> documentation".

-#html_title = None

-

-# A shorter title for the navigation bar.  Default is the same as html_title.

-#html_short_title = None

-

-# The name of an image file (relative to this directory) to place at the top

-# of the sidebar.

-#html_logo = None

-

-# The name of an image file (within the static path) to use as favicon of the

-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

-# pixels large.

-#html_favicon = None

-

-# Add any paths that contain custom static files (such as style sheets) here,

-# relative to this directory. They are copied after the builtin static files,

-# so a file named "default.css" will overwrite the builtin "default.css".

-html_static_path = ['_static']

-

-# Add any extra paths that contain custom files (such as robots.txt or

-# .htaccess) here, relative to this directory. These files are copied

-# directly to the root of the documentation.

-#html_extra_path = []

-

-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

-# using the given strftime format.

-#html_last_updated_fmt = '%b %d, %Y'

-

-# If true, SmartyPants will be used to convert quotes and dashes to

-# typographically correct entities.

-#html_use_smartypants = True

-

-# Custom sidebar templates, maps document names to template names.

-#html_sidebars = {}

-

-# Additional templates that should be rendered to pages, maps page names to

-# template names.

-#html_additional_pages = {}

-

-# If false, no module index is generated.

-#html_domain_indices = True

-

-# If false, no index is generated.

-#html_use_index = True

-

-# If true, the index is split into individual pages for each letter.

-#html_split_index = False

-

-# If true, links to the reST sources are added to the pages.

-#html_show_sourcelink = True

-

-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.

-#html_show_sphinx = True

-

-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.

-#html_show_copyright = True

-

-# If true, an OpenSearch description file will be output, and all pages will

-# contain a <link> tag referring to it.  The value of this option must be the

-# base URL from which the finished HTML is served.

-#html_use_opensearch = ''

-

-# This is the file name suffix for HTML files (e.g. ".xhtml").

-#html_file_suffix = None

-

-# Output file base name for HTML help builder.

-htmlhelp_basename = 'PCBToolsdoc'

-

-

-# -- Options for LaTeX output ---------------------------------------------

-

-latex_elements = {

-# The paper size ('letterpaper' or 'a4paper').

-#'papersize': 'letterpaper',

-

-# The font size ('10pt', '11pt' or '12pt').

-#'pointsize': '10pt',

-

-# Additional stuff for the LaTeX preamble.

-#'preamble': '',

-}

-

-# Grouping the document tree into LaTeX files. List of tuples

-# (source start file, target name, title,

-#  author, documentclass [howto, manual, or own class]).

-latex_documents = [

-  ('index', 'PCBTools.tex', u'PCB Tools Documentation',

-   u'Hamilton Kibbe', 'manual'),

-]

-

-# The name of an image file (relative to this directory) to place at the top of

-# the title page.

-#latex_logo = None

-

-# For "manual" documents, if this is true, then toplevel headings are parts,

-# not chapters.

-#latex_use_parts = False

-

-# If true, show page references after internal links.

-#latex_show_pagerefs = False

-

-# If true, show URL addresses after external links.

-#latex_show_urls = False

-

-# Documents to append as an appendix to all manuals.

-#latex_appendices = []

-

-# If false, no module index is generated.

-#latex_domain_indices = True

-

-

-# -- Options for manual page output ---------------------------------------

-

-# One entry per manual page. List of tuples

-# (source start file, name, description, authors, manual section).

-man_pages = [

-    ('index', 'pcbtools', u'PCB Tools Documentation',

-     [u'Hamilton Kibbe'], 1)

-]

-

-# If true, show URL addresses after external links.

-#man_show_urls = False

-

-

-# -- Options for Texinfo output -------------------------------------------

-

-# Grouping the document tree into Texinfo files. List of tuples

-# (source start file, target name, title, author,

-#  dir menu entry, description, category)

-texinfo_documents = [

-  ('index', 'PCBTools', u'PCB Tools Documentation',

-   u'Hamilton Kibbe', 'PCBTools', 'Tools for working with PCB CAM files.',

-   'Miscellaneous'),

-]

-

-# Documents to append as an appendix to all manuals.

-#texinfo_appendices = []

-

-# If false, no module index is generated.

-#texinfo_domain_indices = True

-

-# How to display URL addresses: 'footnote', 'no', or 'inline'.

-#texinfo_show_urls = 'footnote'

-

-# If true, do not generate a @detailmenu in the "Top" node's menu.

-#texinfo_no_detailmenu = False

diff --git a/doc/source/documentation/excellon.rst b/doc/source/documentation/excellon.rst
deleted file mode 100644
index 9cd7ee1..0000000
--- a/doc/source/documentation/excellon.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-:mod:`excellon` --- Excellon file handling
-==============================================
-
-.. module:: excellon
-   :synopsis: Functions and classes for handling Excellon files
-.. sectionauthor:: Hamilton Kibbe <ham@hamiltonkib.be>
-
-
-The Excellon format is the most common format for exporting PCB drill
-information. The Excellon format is used to program CNC drilling macines for
-drilling holes in PCBs. As such, excellon files are sometimes refererred to as
-NC-drill files.  The Excellon format reference is available 
-`here <http://www.excellon.com/manuals/program.htm>`_. The :mod:`excellon`
-submodule implements classes to read and write excellon files without having
-to know the precise details of the format.
-
-The :mod:`excellon` submodule's :func:`read` function serves as a
-simple interface for parsing excellon files.  The :class:`ExcellonFile` class
-stores all the information contained in an Excellon file allowing the file to
-be analyzed, modified, and updated. The :class:`ExcellonParser` class is used
-in the background for parsing RS-274X files.
-
-.. _excellon-contents:
-
-Functions
----------
-The :mod:`excellon` module defines the following functions:
-
-.. autofunction:: gerber.excellon.read
-    
-
-Classes
--------
-The :mod:`excellon` module defines the following classes:
-
-.. autoclass:: gerber.excellon.ExcellonFile
-    :members:
-    
-
-.. autoclass:: gerber.excellon.ExcellonParser
-    :members:
-    
diff --git a/doc/source/documentation/index.rst b/doc/source/documentation/index.rst
deleted file mode 100644
index dec83f9..0000000
--- a/doc/source/documentation/index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-PCB Tools Reference
-======================
-
-.. toctree::
-    :maxdepth: 2
-
-    Gerber (RS-274X) Files <rs274x>
-    Excellon Files <excellon>
-    Operations <operations>
-    Rendering <render>
diff --git a/doc/source/documentation/operations.rst b/doc/source/documentation/operations.rst
deleted file mode 100644
index 6551236..0000000
--- a/doc/source/documentation/operations.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-:mod:`operations` --- Cam File operations
-=========================================
-
-.. module:: operations
-   :synopsis: Functions for modifying CAM files
-.. sectionauthor:: Hamilton Kibbe <ham@hamiltonkib.be>
-
-
-The :mod:`operations` module provides functions which modify
-:class:`gerber.cam.CamFile` objects. All of the functions in this module
-return a modified copy of the supplied file.
-
-.. _operations-contents:
-
-Functions
----------
-The :mod:`operations` module defines the following functions:
-
-.. autofunction:: gerber.operations.to_inch
-.. autofunction:: gerber.operations.to_metric
-.. autofunction:: gerber.operations.offset
-
-
-
diff --git a/doc/source/documentation/render.rst b/doc/source/documentation/render.rst
deleted file mode 100644
index 324ef71..0000000
--- a/doc/source/documentation/render.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-:mod:`render` --- Gerber file Rendering
-==============================================
-
-.. module:: render
-   :synopsis: Functions and classes for handling Excellon files
-.. sectionauthor:: Hamilton Kibbe <ham@hamiltonkib.be>
-
-Render Module
--------------
-.. automodule:: gerber.render.render
-    :members:
diff --git a/doc/source/documentation/rs274x.rst b/doc/source/documentation/rs274x.rst
deleted file mode 100644
index 064c82f..0000000
--- a/doc/source/documentation/rs274x.rst
+++ /dev/null
@@ -1,37 +0,0 @@
-:mod:`rs274x` --- RS-274X file handling
-==============================================
-
-.. module:: rs274x
-   :synopsis: Functions and classes for handling RS-274X  files
-.. sectionauthor:: Hamilton Kibbe <ham@hamiltonkib.be>
-
-
-The RS-274X (Gerber) format is the most common format for exporting PCB
-artwork.  The Specification is published by Ucamco and is available
-`here <http://www.ucamco.com/files/downloads/file/81/the_gerber_file_format_specification.pdf>`_.
-The :mod:`rs274x` submodule implements classes to read and write
-RS-274X files without having to know the precise details of the format.
-
-The :mod:`rs274x` submodule's :func:`read` function serves as a
-simple interface for parsing gerber files.  The :class:`GerberFile` class
-stores all the information contained in a gerber file allowing the file to be
-analyzed, modified, and updated. The :class:`GerberParser` class is used in
-the background for parsing RS-274X files.
-
-.. _gerber-contents:
-
-Functions
----------
-The :mod:`rs274x` module defines the following functions:
-
-.. autofunction:: gerber.rs274x.read
-
-Classes
--------
-The :mod:`rs274x` module defines the following classes:
-
-.. autoclass:: gerber.rs274x.GerberFile
-    :members:
-
-.. autoclass:: gerber.rs274x.GerberParser
-    :members:
diff --git a/doc/source/features.rst b/doc/source/features.rst
deleted file mode 100644
index 67d9e2a..0000000
--- a/doc/source/features.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-Feature Suppport
-================
-
-Currently supported features are as follows:
-
-============  ========  ===========  ================  ======  =======  =======
-File Format   Parsing    Rendering   Unit Conversion   Scale   Offset   Rotate
-============  ========  ===========  ================  ======  =======  =======
-RS274-X       Yes       Yes          Yes               No      Yes      No
-Excellon      Yes       Yes          Yes               No      Yes      No
-ODB++         No        No           No                No      No       No
-============  ========  ===========  ================  ======  =======  =======
-
-
diff --git a/doc/source/index.rst b/doc/source/index.rst
deleted file mode 100644
index c96ff8a..0000000
--- a/doc/source/index.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-.. PCB-tools documentation master file, created by

-   sphinx-quickstart on Sun Sep 28 18:16:46 2014.

-   You can adapt this file completely to your liking, but it should at least

-   contain the root `toctree` directive.

-

-PCB-Tools

-========================================

-

-Contents:

-

-.. toctree::

-    :maxdepth: 1

-    

-    about

-    features

-    documentation/index

-

-Indices and tables

-==================

-

-* :ref:`genindex`

-* :ref:`modindex`

-* :ref:`search`

-

diff --git a/docs/aperture-macros.rst b/docs/aperture-macros.rst
new file mode 100644
index 0000000..1284c49
--- /dev/null
+++ b/docs/aperture-macros.rst
@@ -0,0 +1,48 @@
+Aperture Macros
+===============
+
+.. autoclass:: gerbonara.aperture_macros.parse.ApertureMacro
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.parse.GenericMacros
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.expression.Expression
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.expression.UnitExpression
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.expression.ConstantExpression
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.expression.VariableExpression
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.expression.OperatorExpression
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.primitive.Primitive
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.primitive.Circle
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.primitive.VectorLine
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.primitive.CenterLine
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.primitive.Polygon
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.primitive.Thermal
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.primitive.Outline
+    :members:
+
+.. autoclass:: gerbonara.aperture_macros.primitive.Comment
+    :members:
+
diff --git a/docs/apertures.rst b/docs/apertures.rst
new file mode 100644
index 0000000..2a17a04
--- /dev/null
+++ b/docs/apertures.rst
@@ -0,0 +1,138 @@
+Apertures in Gerbonara
+======================
+
+Gerbonara maps all standard Gerber apertures to subclasses of the Aperture_ class. These subclasses: CircleAperture_,
+RectangleAperture_, ObroundAperture_ and PolygonAperture_. Aperture macro instantiations get mapped to
+ApertureMacroInstance_ (also an Aperture_ subclass).
+
+All Aperture_ subclasses have these common attributes:
+
+
+`hole_dia`
+    float with diameter of hole. 0 for no hole.
+
+`hole_rect_h`
+    float or None. If not None, specifies a rectangular hole of size `hole_dia * hole_rect_h` instead of a round hole.
+
+`unit`
+    LengthUnit_ for all of this aperture's fields
+
+`attrs`
+    GerberX2 attributes of this aperture. Note that this will only contain aperture attributes, not file attributes.
+    File attributes are stored in the `attrs` of GerberFile_.
+
+`original_number`
+    int of aperture index this aperture had when it was read from the Gerber file. This field is purely informational
+    since apertures are de-duplicated and re-numbered when writing a Gerber file. For `D10`, this field would be `10`.
+    If you programmatically create a new aperture, you do not have to set this.
+
+`rotation`
+    Aperture rotation in radians counter-clockwise. This field is not part of the Gerber standard. Standard rectangle
+    and obround apertures do not support rotation. Gerbonara converts rotated apertures into aperture macros during
+    Gerber export as necessary.
+
+CircleAperture
+--------------
+
+This is the only one valid for use in Line_ or Arc_.
+
+Attributes:
+
+Common attributes:
+    `hole_dia`, `hole_rect_h`, `unit`, `attrs`, and `original_number`. `rotation` is present but has no effect in
+    CircleAperture_.
+
+`diameter`
+    float with diameter of aperture in the unit from the aperture's `unit` field. 
+    
+RectangleAperture
+-----------------
+
+Common attributes:
+    `hole_dia`, `hole_rect_h`, `unit`, `attrs`, `original_number`, and `rotation`
+
+`w`, `h`
+    floats with width or height of rectangle in units from the aperture's `unit` field. 
+
+ObroundAperture
+---------------
+
+Aperture whose shape is the convex hull of two circles of equal radii.
+
+Common attributes:
+    `hole_dia`, `hole_rect_h`, `unit`, `attrs`, `original_number`, and `rotation`
+
+`w`, `h`
+    floats with width and height of bounding box of obround. The smaller one of these will be the diameter of the
+    obround's ends. If `w` is larger, the result will be a landscape obround. If `h` is larger, it will be a portrait
+    obround.
+
+PolygonAperture
+---------------
+
+Aperture whose shape is a regular n-sided polygon (e.g. pentagon, hexagon etc.).
+
+
+Common attributes:
+    `hole_dia`, `unit`, `attrs`, `original_number`, and `rotation`. `hole_rect_h` is not supported in PolygonAperture_
+    since the Gerber spec does not list it.
+
+`diameter`
+    float with diameter of circumscribing circle, i.e. the circle that all the polygon's corners lie on.
+
+`n_vertices`
+    int with number of corners of this polygon. Three for a triangle, four for a square, five for a pentagon etc.
+
+ApertureMacroInstance
+---------------------
+
+One instance of an aperture macro. An aperture macro defined with an `AM` statement can be instantiated by multiple `AD`
+aperture definition statements using different parameters. An ApertureMacroInstance_ is one such binding of a macro to a
+particular set of parameters. Note that you still need an ApertureMacroInstance_ even if your ApertureMacro_ has no
+parameters since an ApertureMacro_ is not an Aperture_ by itself.
+
+Attributes:
+
+Common attributes:
+    `unit`, `attrs`, `original_number`, and `rotation`. ApertureMacroInstance_ does not support `hole_dia` or
+    `hole_rect_h`. `rotation` is handled by re-writing the ApertureMacro_ during export.
+
+`macro`
+    The ApertureMacro_ that is bound here
+
+`parameters`
+    list of ints or floats with the parameters for this macro. The first element is `$1`, the second is `$2` etc.
+
+ExcellonTool
+------------
+
+Special Aperture_ subclass for use in ExcellonFile_. Similar to CircleAperture_, but does not have `hole_dia` or
+`hole_rect_h`, and has additional `plated` and `depth_offset` attributes.
+
+
+Common attributes:
+    `unit`, `original_number`
+
+`plated`
+    bool or None. True if this hole/slot is copper-plated, False if not, and None if it is undefined or unknown.
+
+`depth_offset`
+    float with Excellon depth offset for this hole or slot. If the fab supports this, this can be used to create
+    features that do not go all the way through the board.
+
+Aperture generalization
+-----------------------
+
+Gerbonara supports rotating both individual graphic objects and whole files. Alas, this was not a use case that was
+intended when the Gerber format was developed. We can rotate lines, arcs, and regions alright by simply rotatint all of
+their points. Flashes are where things get tricky: Individual flashes cannot be rotated at all in any widely supported
+way. There are some newer additions to the standard, but I would be surprised if any of the cheap board houses
+understand those. The only way to rotate a flash is to rotate the aperture, not the flash. For cirlces, this is a no-op.
+For polygons, we simply change the angle parameter. However, for rectangles and obrounds this gets tricky: Neither one
+supports a rotation parameter. The only way to rotate these is to convert them to an aperture macro, then rotate that.
+
+This behavior of using aperture macros for general rotated rectangles is common behavior among CAD tools. Gerbonara adds
+a non-standard `rotation` attribute to all apertures except CircleAperture_ and transparently converts rotated instances
+to the appropriate ApertureMacroInstance_ objects while it writes out the file. Be aware that this may mean that an
+object that in memory has a RectangleAperture_ might end up with an aperture macro instance in the output Gerber file.
+
diff --git a/docs/api-concepts.rst b/docs/api-concepts.rst
new file mode 100644
index 0000000..075498b
--- /dev/null
+++ b/docs/api-concepts.rst
@@ -0,0 +1,60 @@
+Gerbonara API concepts
+======================
+
+High-level overview
+-------------------
+
+Gerbonara's API is split into three larger sub-areas:
+
+**File API**
+    This is where the main user interface classes live: :py:class:`.LayerStack` (for opening a directory/zip full of
+    files, and automatically matching file roles based on filenames), :py:class:`.GerberFile` (for opening an individual
+    RS-274X file), :py:class:`.ExcellonFile` (for Excellon drill files) and :py:class:`.Netlist` (for IPC-356 netlist
+    files).
+
+**Graphic Object API**
+    This is where the nuts and bolts inside a :py:class:`.GerberFile` or :py:class:`.ExcellonFile` such as
+    :py:class:`~.graphic_objects.Line`, :py:class:`~.graphic_objects.Arc`, :py:class:`.Region` and :py:class:`.Flash`
+    live. Everything in here has explicit unit support. A part of the Graphic object API is the :doc:`Aperture
+    API<apertures>`.
+
+**Graphic Primitive API**
+    This is a rendering abstraction layer. Graphic objects can be converted into graphic primitives for rendering.
+    Graphic primitives are unit-less. Units are converted during :py:class:`.GraphicObject` to
+    :py:class:`.GraphicPrimitive` rendering.
+
+The hierarchy works like: A :py:class:`.LayerStack` contains either a :py:class:`.GerberFile`, an
+:py:class:`.ExcellonFile` or a :py:class:`.Netlist` for each layer. Each of these file objects contains a number of
+:py:class:`.GraphicObject` instances such as :py:class:`~.graphic_objects.Line` or :py:class:`.Flash`. These objects can
+easily be changed or deleted, and new ones can be created programmatically. For rendering, each of these objects as well
+as file objects can be rendered into :py:class:`.GraphicPrimitive` instances using
+:py:meth:`.GraphicObject.to_primitives`.
+
+Apertures
+---------
+
+Gerber apertures are represented by subclasses of :py:class:`.Aperture` such as :py:class:`.CircleAperture`. An instance
+of an aperture class is stored inside the :py:attr:`~.graphic_objects.Line.aperture` field of a
+:py:class:`.GraphicObject`. :py:class:`.GraphicObject` subclasses that have an aperture are
+:py:class:`~.graphic_objects.Line`, :py:class:`~.graphic_objects.Arc` and :py:class:`.Flash`. You can create and
+duplicate :py:class:`.Aperture` objects as needed. They are automatically de-duplicated when a Gerber file is written.
+
+Gerbonara has full aperture macro support. Each aperture macro is represented by an :py:class:`.parse.ApertureMacro`
+instance. Like apertures, :py:class:`.parse.ApertureMacro` instances are de-duplicated when writing a file. An aperture
+macro-based aperture definition is represented by the :py:class:`.ApertureMacroInstance` subclass of
+:py:class:`.Aperture`. An aperture macro instance basically binds an aperture macro to a given set of macro parameters.
+Note that even if a macro does not accept any parameters you still cannot directly stick it into the aperture field of a
+graphic object, and instead need to wrap it inside an :py:class:`.ApertureMacroInstance` first. 
+
+Excellon vs. Gerber
+-------------------
+
+Excellon files use the same graphic object classes as Gerber files. Inside an Excellon file, only
+:py:class:`~.graphic_objects.Line`, :py:class:`~.graphic_objects.Arc` and :py:class:`.Flash` are allowed. Lines and arcs map to milled
+Excellon slots. Excellon drills are mapped to :py:class:`.Flash` instances. 
+
+Excellon drills are internally handled using a special :py:class:`.ExcellonTool` aperture class. When you put a
+:py:class:`.GraphicObject` from an Excellon file into a Gerber file, these become circular apertures. You can also take
+objects from an Excellon file and put them into a Gerber file if they have a simple :py:class:`.CircleAperture`. Copying
+objects with other apertures into an Excellon file will raise an error when saving. 
+
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..915f0dc
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+from pathlib import Path
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent.absolute()))
+
+# -- Project information -----------------------------------------------------
+
+project = 'gerbonara'
+copyright = '2022, Jan Götte'
+author = 'jaseg'
+
+# The full version, including alpha/beta/rc tags
+release = '0.9.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+]
+
+autodoc_member_order = 'groupwise'
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
diff --git a/docs/file-api.rst b/docs/file-api.rst
new file mode 100644
index 0000000..d73b5f1
--- /dev/null
+++ b/docs/file-api.rst
@@ -0,0 +1,25 @@
+Layers and Files
+================
+
+Gerbonara currently supports three file types: RS-274-X Gerber as `specified by Ucamco
+<https://www.ucamco.com/en/gerber>`:py:class:`._` through :py:class:`.GerberFile`, Excellon/XNC through
+:py:class:`.ExcellonFile`, and IPC-356 netlists through :py:class:`.Netlist`.
+
+Usually, a PCB is sent to a manufacturer as a bundle of several of these files. Such a bundle of files (each of which is
+either a :py:class:`.GerberFile` or an :py:class:`.ExcellonFile`) is represented by :py:class:`.LayerStack`.
+:py:class:`.LayerStack` contains logic to automatcally
+recognize a wide variety of CAD tools from file name and syntactic hints, and can automatically match all files in a
+folder to their appropriate layers.
+
+.. autoclass:: gerbonara.layers.LayerStack
+   :members:
+
+.. autoclass:: gerbonara.rs274x.GerberFile
+   :members:
+
+.. autoclass:: gerbonara.excellon.ExcellonFile
+   :members:
+
+.. autoclass:: gerbonara.ipc356.Netlist
+   :members:
+
diff --git a/docs/graphic-primitive-api.rst b/docs/graphic-primitive-api.rst
new file mode 100644
index 0000000..d506e87
--- /dev/null
+++ b/docs/graphic-primitive-api.rst
@@ -0,0 +1,27 @@
+Graphic Primitives
+==================
+
+.. autoclass:: gerbonara.graphic_primitives.GraphicPrimitive
+    :members:
+
+.. autoclass:: gerbonara.graphic_primitives.Circle
+    :members:
+
+.. autoclass:: gerbonara.graphic_primitives.Obround
+    :members:
+
+.. autoclass:: gerbonara.graphic_primitives.ArcPoly
+    :members:
+
+.. autoclass:: gerbonara.graphic_primitives.Line
+    :members:
+
+.. autoclass:: gerbonara.graphic_primitives.Arc
+    :members:
+
+.. autoclass:: gerbonara.graphic_primitives.Rectangle
+    :members:
+
+.. autoclass:: gerbonara.graphic_primitives.RegularPolygon
+    :members:
+
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
+
diff --git a/docs/object-api.rst b/docs/object-api.rst
new file mode 100644
index 0000000..f6345b9
--- /dev/null
+++ b/docs/object-api.rst
@@ -0,0 +1,30 @@
+Graphic Objects
+===============
+
+Graphic objects are the lego blocks a gerbonara :py:class:`gerbonara.rs274x.GerberFile` or
+:py:class:`gerbonara.excellon.ExcellonFile` is built from. They are stored in the file's
+:py:attr:`gerbonara.rs274x.GerberFile.objects` list. You can directly manipulate that list from code.
+
+There are four graphic object types: :py:class:`gerbonara.graphic_objects.Flash`,
+:py:class:`gerbonara.graphic_objects.Line`, :py:class:`gerbonara.graphic_objects.Arc`, and
+:py:class:`gerbonara.graphic_objects.Region` . All of them are derived from
+:py:class:`gerbonara.graphic_objects.GraphicObject`.
+
+.. autoclass:: gerbonara.graphic_objects.GraphicObject
+   :members:
+
+.. autoclass:: gerbonara.graphic_objects.Flash
+   :members:
+
+.. autoclass:: gerbonara.graphic_objects.Line
+   :members:
+
+.. autoclass:: gerbonara.graphic_objects.Arc
+   :members:
+
+.. autoclass:: gerbonara.graphic_objects.Region
+   :members:
+
+.. _pcb-tools: https://github.com/opiopan/pcb-tools-extension
+.. _gerbolyze: https://github.com/jaseg/gerbolyze
+.. _svg-flatten: https://github.com/jaseg/gerbolyze/tree/main/svg-flatten
diff --git a/docs/utilities.rst b/docs/utilities.rst
new file mode 100644
index 0000000..89b1cde
--- /dev/null
+++ b/docs/utilities.rst
@@ -0,0 +1,3 @@
+Utilities
+=========
+
diff --git a/gerbonara/apertures.py b/gerbonara/apertures.py
index ab62077..086d5b1 100644
--- a/gerbonara/apertures.py
+++ b/gerbonara/apertures.py
@@ -95,6 +95,7 @@ class Aperture:
 
 @dataclass(unsafe_hash=True)
 class ExcellonTool(Aperture):
+    gerber_shape_code = 'C'
     human_readable_shape = 'drill'
     diameter : Length(float)
     plated : bool = None
diff --git a/gerbonara/excellon.py b/gerbonara/excellon.py
index 3382ffe..96a78be 100755
--- a/gerbonara/excellon.py
+++ b/gerbonara/excellon.py
@@ -197,6 +197,9 @@ class ExcellonFile(CamFile):
         else:
             self.objects.append(obj_or_comment)
 
+    def to_excellon(self):
+        return self
+
     def to_gerber(self):
         apertures = {}
         out = GerberFile()
@@ -292,7 +295,7 @@ class ExcellonFile(CamFile):
 
         yield 'M30'
 
-    def to_excellon(self, settings=None, drop_comments=True):
+    def generate_excellon(self, settings=None, drop_comments=True):
         ''' Export to Excellon format. This function always generates XNC, which is a well-defined subset of Excellon.
         '''
         if settings is None:
@@ -306,10 +309,11 @@ class ExcellonFile(CamFile):
 
     def save(self, filename, settings=None, drop_comments=True):
         with open(filename, 'w') as f:
-            f.write(self.to_excellon(settings, drop_comments=drop_comments))
+            f.write(self.generate_excellon(settings, drop_comments=drop_comments))
 
     def offset(self, x=0, y=0, unit=MM):
-        self.objects = [ obj.with_offset(x, y, unit) for obj in self.objects ]
+        for obj in self.objects:
+            obj.offset(x, y, unit)
 
     def rotate(self, angle, cx=0, cy=0, unit=MM):
         if math.isclose(angle % (2*math.pi), 0):
diff --git a/gerbonara/graphic_objects.py b/gerbonara/graphic_objects.py
index 1f475a6..99f990f 100644
--- a/gerbonara/graphic_objects.py
+++ b/gerbonara/graphic_objects.py
@@ -1,8 +1,9 @@
 
 import math
+import copy
 from dataclasses import dataclass, KW_ONLY, astuple, replace, field, fields
 
-from .utils import MM, InterpMode
+from .utils import MM, InterpMode, to_unit
 from . import graphic_primitives as gp
 
 
@@ -18,27 +19,94 @@ class Length:
     def __init__(self, obj_type):
         self.type = obj_type
 
+    def __repr__(self):
+        # This makes the automatically generated method signatures in the Sphinx docs look nice
+        return 'float'
+
 @dataclass
-class GerberObject:
+class GraphicObject:
+    """ Base class for the graphic objects that make up a :py:class:`gerbonara.rs274x.GerberFile` or
+    :py:class:`gerbonara.excellon.ExcellonFile`. """
     _ : KW_ONLY
+
+    #: bool representing the *color* of this feature: whether this is a *dark* or *clear* feature. Clear and dark are
+    #: meant in the sense that they are used in the Gerber spec and refer to whether the transparency film that this
+    #: file describes ends up black or clear at this spot. In a standard green PCB, a *polarity_dark=True* line will
+    #: show up as copper on the copper layer, white ink on the silkscreen layer, or an opening on the soldermask layer.
+    #: Clear features erase dark features, they are not transparent in the colloquial meaning. This property is ignored
+    #: for features of an :py:class:`gerbonara.excellon.ExcellonFile`.
     polarity_dark : bool = True
+
+    #: :py:class:`gerbonara.utils.LengthUnit` used for all coordinate fields of this feature (such as `x` or `y`).
     unit : str = None
+
+
+    #: `dict` containing GerberX2 attributes attached to this feature. Note that this does not include file attributes,
+    #: which are stored in the :py:class:`gerbonara.rs274x.GerberFile` object instead.
     attrs : dict = field(default_factory=dict)
 
     def converted(self, unit):
-        return replace(self, 
-                **{ f.name: self.unit.convert_to(unit, getattr(self, f.name))
-                    for f in fields(self) if type(f.type) is Length })
+        """ Convert this gerber object to another :py:class:`gerbonara.utils.LengthUnit`.
+
+        :param unit: Either a :py:class:`gerbonara.utils.LengthUnit` instance or one of the strings ``'mm'`` or ``'inch'``.
+
+        :returns: A copy of this object using the new unit. 
+        """
+        copy = copy.copy(self)
+        copy.convert_to(unit)
+
+    def convert_to(self, unit):
+        """ Convert this gerber object to another :py:class:`gerbonara.utils.LengthUnit` in-place.
+
+        :param unit: Either a :py:class:`gerbonara.utils.LengthUnit` instance or one of the strings ``'mm'`` or ``'inch'``.
+        """
+
+        for f in fields(self):
+            if type(f.type) is Length:
+                setattr(self, f.name, self.unit.convert_to(unit, getattr(self, f.name)))
+
+        self.unit = to_unit(unit)
+
+    def offset(self, dx, dy, unit=MM):
+        """ Add an offset to the location of this feature. The location can be given in either unit, and is
+        automatically converted into this object's local unit.
+        
+        :param float dx: X offset, positive values move the object right.
+        :param float dy: Y offset, positive values move the object up. This is the opposite of the normal screen
+                         coordinate system used in SVG and other computer graphics APIs.
+        """
 
-    def with_offset(self, dx, dy, unit=MM):
         dx, dy = self.unit(dx, unit), self.unit(dy, unit)
-        return self._with_offset(dx, dy)
+        self._offset(dx, dy)
 
     def rotate(self, rotation, cx=0, cy=0, unit=MM):
+        """ Rotate this object. The center of rotation can be given in either unit, and is automatically converted into
+        this object's local unit.
+
+        .. note:: The center's Y coordinate as well as the angle's polarity are flipped compared to computer graphics
+                  convention since Gerber uses a bottom-to-top Y axis.
+
+        :param float rotation: rotation in radians clockwise.
+        :param float cx: X coordinate of center of rotation in *unit* units.
+        :param float cy: Y coordinate of center of rotation. (0,0) is at the bottom left of the image.
+        :param unit: :py:class:`gerbonara.utils.LengthUnit` or str with unit for *cx* and *cy*
+        """
+
         cx, cy = self.unit(cx, unit), self.unit(cy, unit)
         self._rotate(rotation, cx, cy)
 
     def bounding_box(self, unit=None):
+        """ Return axis-aligned bounding box of this object in given unit. If no unit is given, return the bounding box
+        in the object's local unit (``self.unit``).
+
+        .. note:: This method returns bounding boxes in a different format than legacy pcb-tools_, which used
+                  ``(min_x, max_x), (min_y, max_y)``
+
+        :param unit: :py:class:`gerbonara.utils.LengthUnit` or str with unit for return value.
+
+        :returns: tuple of tuples of floats: ``(min_x, min_y), (max_x, max_y)``
+        """
+
         bboxes = [ p.bounding_box() for p in self.to_primitives(unit) ]
         min_x = min(min_x for (min_x, _min_y), _ in bboxes)
         min_y = min(min_y for (_min_x, min_y), _ in bboxes)
@@ -47,16 +115,62 @@ class GerberObject:
         return ((min_x, min_y), (max_x, max_y))
 
     def to_primitives(self, unit=None):
-        raise NotImplementedError()
+        """ Render this object into low-level graphical primitives (subclasses of :py:class:`GraphicPrimitive`). This
+        computes out all coordinates in case aperture macros are involved, and resolves units. The output primitives are
+        converted into the given unit, and will be stripped of unit information. If no unit is given, use this object's
+        native unit (``self.unit``).
+
+        :param unit: :py:class:`gerbonara.utils.LengthUnit` or str with unit for return value.
+
+        :rtype: Iterator[:py:class:`GraphicPrimitive`]
+        """
+        return self._to_primitives(unit)
+
+    def _to_statements(self, gs):
+        """ Serialize this object into Gerber statements.
+
+        :param gs: :py:class:`rs274x.GraphicsState` object containing current Gerber state (polarity, selected aperture,
+        interpolation mode etc.).
+
+        :returns: Iterator yielding one string per line of output Gerber
+        :rtype: Iterator[str]
+        """
+        self._to_statements(gs)
+
+    def _to_xnc(self, ctx):
+        """ Serialize this object into XNC Excellon statements.
+
+        :param ctx: :py:class:`excellon.ExcellonContext` object containing current Excellon state (selected tool,
+        interpolation mode etc.).
+
+        :returns: Iterator yielding one string per line of output XNC code
+        :rtype: Iterator[str]
+        """
+        self._to_xnc(ctx)
+
 
 @dataclass
-class Flash(GerberObject):
+class Flash(GraphicObject):
+    """ A flash is what happens when you "stamp" a Gerber aperture at some location. The :py:attr:`polarity_dark`
+    attribute that Flash inherits from :py:class:`GraphicObject` is ``True`` for normal flashes. If you set a Flash's
+    ``polarity_dark`` to ``False``, you invert the polarity of all of its features.
+
+    Flashes are also used to represent drilled holes in an :py:class:`gerbonara.excellon.ExcellonFile`. In this case,
+    :py:attr:`aperture` should be an instance of :py:class:`ExcellonTool`.
+    """
+
+    #: float with X coordinate of the center of this flash.
     x : Length(float)
+
+    #: float with Y coordinate of the center of this flash.
     y : Length(float)
+
+    #: Flashed Aperture. must be a subclass of :py:class:`Aperture`.
     aperture : object
 
     @property
     def tool(self):
+        """ Alias for :py:attr:`aperture` for use inside an :py:class:`gerbonara.excellon.ExcellonFile`. """
         return self.aperture
 
     @tool.setter
@@ -65,19 +179,23 @@ class Flash(GerberObject):
 
     @property
     def plated(self):
-        return self.tool.plated
+        """ (Excellon only) Returns if this is a plated hole. ``True`` (plated), ``False`` (non-plated) or ``None``
+        (plating undefined)
+        """
+        return getattr(self.tool, 'plated', None)
 
-    def _with_offset(self, dx, dy):
-        return replace(self, x=self.x+dx, y=self.y+dy)
+    def __offset(self, dx, dy):
+        self.x += dx
+        self.y += dy
 
     def _rotate(self, rotation, cx=0, cy=0):
         self.x, self.y = gp.rotate_point(self.x, self.y, rotation, cx, cy)
 
-    def to_primitives(self, unit=None):
+    def _to_primitives(self, unit=None):
         conv = self.converted(unit)
         yield from self.aperture.flash(conv.x, conv.y, unit, self.polarity_dark)
 
-    def to_statements(self, gs):
+    def _to_statements(self, gs):
         yield from gs.set_polarity(self.polarity_dark)
         yield from gs.set_aperture(self.aperture)
 
@@ -87,7 +205,7 @@ class Flash(GerberObject):
 
         gs.update_point(self.x, self.y, unit=self.unit)
 
-    def to_xnc(self, ctx):
+    def _to_xnc(self, ctx):
         yield from ctx.select_tool(self.tool)
         yield from ctx.drill_mode()
 
@@ -97,11 +215,31 @@ class Flash(GerberObject):
 
         ctx.set_current_point(self.unit, self.x, self.y)
 
+    # internally used to compute Excellon file path length
     def curve_length(self, unit=MM):
         return 0
 
 
-class Region(GerberObject):
+class Region(GraphicObject):
+    """ Gerber "region", roughly equivalent to what in computer graphics you would call a polygon. A region is a single
+    filled area defined by a list of coordinates on its contour. A region's polarity is its "fill". A region does not
+    have a "stroke", and thus does not have an `aperture` field. Note that regions are a strict subset of what modern
+    computer graphics considers a polygon or path. Be careful when converting shapes from somewhere else into Gerber
+    regions. For arbitrary shapes (e.g. SVG paths) this is non-trivial, and I recommend you hava look at Gerbolyze_ /
+    svg-flatten_. Here's a list of special features of Gerber regions:
+
+     * A region's outline consists of straigt line segments and circular arcs and must always be closed.
+     * A region is always exactly one connected component.
+     * A region must not overlap itself anywhere.
+     * A region cannot have holes.
+
+    There is one exception from the last two rules: To emulate a region with a hole in it, *cut-ins* are allowed. At a
+    cut-in, the region is allowed to touch (but never overlap!) itself.
+
+    :attr poly: :py:class:`graphic_primitives.ArcPoly` describing the actual outline of this Region. The coordinates of
+                this poly are in the unit of this instance's :py:attr:`unit` field.
+    """
+
     def __init__(self, outline=None, arc_centers=None, *, unit, polarity_dark):
         super().__init__(unit=unit, polarity_dark=polarity_dark)
         outline = [] if outline is None else outline
@@ -114,11 +252,8 @@ class Region(GerberObject):
     def __bool__(self):
         return bool(self.poly)
 
-    def _with_offset(self, dx, dy):
-        return Region([ (x+dx, y+dy) for x, y in self.poly.outline ],
-                self.poly.arc_centers,
-                polarity_dark=self.polarity_dark,
-                unit=self.unit)
+    def _offset(self, dx, dy):
+        self.poly.outline = [ (x+dx, y+dy) for x, y in self.poly.outline ]
 
     def _rotate(self, angle, cx=0, cy=0):
         self.poly.outline = [ gp.rotate_point(x, y, angle, cx, cy) for x, y in self.poly.outline ]
@@ -138,7 +273,7 @@ class Region(GerberObject):
         else:
             self.poly.arc_centers.append(None)
 
-    def to_primitives(self, unit=None):
+    def _to_primitives(self, unit=None):
         self.poly.polarity_dark = self.polarity_dark # FIXME: is this the right spot to do this?
         if unit == self.unit:
             yield self.poly
@@ -188,17 +323,37 @@ class Region(GerberObject):
         yield 'G37*'
 
 @dataclass
-class Line(GerberObject):
-    # Line with *round* end caps.
+class Line(GraphicObject):
+    """ A line is what happens when you "drag" a Gerber :py:class:`Aperture` from one point to another. Note that Gerber
+    lines are substantially funkier than normal lines as we know them from modern computer graphics such as SVG. A
+    Gerber line is defined as the area that is covered when you drag its aperture along. This means that for a
+    rectangular aperture, a horizontal line and a vertical line using the same aperture will have different widths.
+
+    .. warning:: Try to only ever use :py:class:`CircleAperture` with :py:class:`Line` and :py:class:`Arc` since other
+                 aperture types are not widely supported by renderers / photoplotters even though they are part of the
+                 spec.
+
+    .. note:: If you manipulate a :py:class:`Line`, it is okay to assume that it has round end caps and a defined width
+              as exceptions are really rare.
+    """
 
+    #: X coordinate of start point
     x1 : Length(float)
+    #: Y coordinate of start point
     y1 : Length(float)
+    #: X coordinate of end point
     x2 : Length(float)
+    #: Y coordinate of end point
     y2 : Length(float)
+    #: Aperture for this line. Should be a subclass of :py:class:`CircleAperture`, whose diameter determines the line
+    #: width.
     aperture : object
 
-    def _with_offset(self, dx, dy):
-        return replace(self, x1=self.x1+dx, y1=self.y1+dy, x2=self.x2+dx, y2=self.y2+dy)
+    def _offset(self, dx, dy):
+        self.x1 += dx
+        self.y1 += dy
+        self.x2 += dx
+        self.y2 += dy
 
     def _rotate(self, rotation, cx=0, cy=0):
         self.x1, self.y1 = gp.rotate_point(self.x1, self.y1, rotation, cx, cy)
@@ -206,18 +361,17 @@ class Line(GerberObject):
 
     @property
     def p1(self):
+        """ Convenience alias for ``(self.x1, self.y1)`` returning start point of the line. """
         return self.x1, self.y1
 
     @property
     def p2(self):
+        """ Convenience alias for ``(self.x2, self.y2)`` returning end point of the line. """
         return self.x2, self.y2
 
     @property
-    def end_point(self):
-        return self.p2
-
-    @property
     def tool(self):
+        """ Alias for :py:attr:`aperture` for use inside an :py:class:`gerbonara.excellon.ExcellonFile`. """
         return self.aperture
 
     @tool.setter
@@ -226,14 +380,17 @@ class Line(GerberObject):
 
     @property
     def plated(self):
+        """ (Excellon only) Returns if this is a plated hole. ``True`` (plated), ``False`` (non-plated) or ``None``
+        (plating undefined)
+        """
         return self.tool.plated
 
-    def to_primitives(self, unit=None):
+    def _to_primitives(self, unit=None):
         conv = self.converted(unit)
         w = self.aperture.equivalent_width(unit) if self.aperture else 0.1 # for debugging
         yield gp.Line(*conv.p1, *conv.p2, w, polarity_dark=self.polarity_dark)
 
-    def to_statements(self, gs):
+    def _to_statements(self, gs):
         yield from gs.set_polarity(self.polarity_dark)
         yield from gs.set_aperture(self.aperture)
         yield from gs.set_interpolation_mode(InterpMode.LINEAR)
@@ -245,7 +402,7 @@ class Line(GerberObject):
 
         gs.update_point(*self.p2, unit=self.unit)
 
-    def to_xnc(self, ctx):
+    def _to_xnc(self, ctx):
         yield from ctx.select_tool(self.tool)
         yield from ctx.route_mode(self.unit, *self.p1)
 
@@ -255,26 +412,61 @@ class Line(GerberObject):
 
         ctx.set_current_point(self.unit, *self.p2)
 
+    # internally used to compute Excellon file path length
     def curve_length(self, unit=MM):
         return self.unit.convert_to(unit, math.dist(self.p1, self.p2))
 
 
 @dataclass
-class Arc(GerberObject):
+class Arc(GraphicObject):
+    """ Like :py:class:`Line`, but a circular arc. Has start ``(x1, y1)`` and end ``(x2, y2)`` attributes like a
+    :py:class:`Line`, but additionally has a center ``(cx, cy)`` specified relative to the start point ``(x1, y1)``, as
+    well as a ``clockwise`` attribute indicating the arc's direction.
+
+    .. note:: The same warning on apertures that applies to :py:class:`Line` applies to :py:class:`Arc`, too.
+    
+    .. warning:: When creating your own circles, you have to take care yourself that the center is actually the center
+                 of a circle that goes through both (x1,y1) and (x2,y2). Elliptical arcs are *not* supported by either
+                 us or the Gerber standard.
+    """
+    #: X coordinate of start point
     x1 : Length(float)
+    #: Y coordinate of start point
     y1 : Length(float)
+    #: X coordinate of end point
     x2 : Length(float)
+    #: Y coordinate of end point
     y2 : Length(float)
-    # relative to (x1, x2)
+    #: X coordinate of arc center relative to ``x1``
     cx : Length(float)
+    #: Y coordinate of arc center relative to ``x1``
     cy : Length(float)
+    #: Direction of arc. ``True`` means clockwise. For a given center coordinate and endpoints there are always two
+    #: possible arcs, the large one and the small one. Flipping this switches between them.
     clockwise : bool
+    #: Aperture for this arc. Should be a subclass of :py:class:`CircleAperture`, whose diameter determines the line
+    #: width.
     aperture : object
     
-    def _with_offset(self, dx, dy):
-        return replace(self, x1=self.x1+dx, y1=self.y1+dy, x2=self.x2+dx, y2=self.y2+dy)
+    def _offset(self, dx, dy):
+        self.x1 += dx
+        self.y1 += dy
+        self.x2 += dx
+        self.y2 += dy
 
     def numeric_error(self, unit=None):
+        """ Gerber arcs are sligtly over-determined. Since we have not just a radius, but center X and Y coordinates, an
+        "impossible" arc can be specified, where the start and end points do not lie on a circle around its center. This
+        function returns the absolute difference between the two radii (start - center) and (end - center) as an
+        indication on how bad this arc is.
+
+        .. note:: For arcs read from a Gerber file, this value can easily be in the order of magnitude of 1e-4. Gerber
+                  files have very limited numerical resolution, and rounding errors will necessarily lead to numerical
+                  accuracy issues with arcs.
+
+        :rtype: float
+        """
+        # This function is used internally to determine the right arc in multi-quadrant mode
         conv = self.converted(unit)
         cx, cy = conv.cx + conv.x1, conv.cy + conv.y1
         r1 = math.dist((cx, cy), conv.p1)
@@ -282,6 +474,11 @@ class Arc(GerberObject):
         return abs(r1 - r2)
 
     def sweep_angle(self):
+        """ Calculate absolute sweep angle of arc. This is always a positive number.
+
+        :returns: Angle in clockwise radian between ``0`` and ``2*math.pi``
+        :rtype: float
+        """
         cx, cy = self.cx + self.x1, self.cy + self.y1
         x1, y1 = self.x1 - cx, self.y1 - cy
         x2, y2 = self.x2 - cx, self.y2 - cy
@@ -301,26 +498,35 @@ class Arc(GerberObject):
 
     @property
     def p1(self):
+        """ Convenience alias for ``(self.x1, self.y1)`` returning start point of the arc. """
         return self.x1, self.y1
 
     @property
     def p2(self):
+        """ Convenience alias for ``(self.x2, self.y2)`` returning end point of the arc. """
         return self.x2, self.y2
 
     @property
     def center(self):
+        """ Returns the center of the arc in **absolute** coordinates.
+
+        :returns: ``(self.x1 + self.cx, self.y1 + self.cy)``
+        :rtype: tuple(float)
+        """
         return self.cx + self.x1, self.cy + self.y1
 
     @property
     def center_relative(self):
-        return self.cx, self.cy
+        """ Returns the center of the arc in relative coordinates.
 
-    @property
-    def end_point(self):
-        return self.p2
+        :returns: ``(self.cx, self.cy)``
+        :rtype: tuple(float)
+        """
+        return self.cx, self.cy
 
     @property
     def tool(self):
+        """ Alias for :py:attr:`aperture` for use inside an :py:class:`gerbonara.excellon.ExcellonFile`. """
         return self.aperture
 
     @tool.setter
@@ -329,6 +535,9 @@ class Arc(GerberObject):
 
     @property
     def plated(self):
+        """ (Excellon only) Returns if this is a plated hole. ``True`` (plated), ``False`` (non-plated) or ``None``
+        (plating undefined)
+        """
         return self.tool.plated
 
     def _rotate(self, rotation, cx=0, cy=0):
@@ -338,7 +547,7 @@ class Arc(GerberObject):
         self.x2, self.y2 = gp.rotate_point(self.x2, self.y2, rotation, cx, cy)
         self.cx, self.cy = new_cx - self.x1, new_cy - self.y1
 
-    def to_primitives(self, unit=None):
+    def _to_primitives(self, unit=None):
         conv = self.converted(unit)
         w = self.aperture.equivalent_width(unit) if self.aperture else 0.1 # for debugging
         yield gp.Arc(x1=conv.x1, y1=conv.y1,
@@ -348,7 +557,7 @@ class Arc(GerberObject):
                 width=w,
                 polarity_dark=self.polarity_dark)
 
-    def to_statements(self, gs):
+    def _to_statements(self, gs):
         yield from gs.set_polarity(self.polarity_dark)
         yield from gs.set_aperture(self.aperture)
         # TODO is the following line correct?
@@ -363,7 +572,7 @@ class Arc(GerberObject):
 
         gs.update_point(*self.p2, unit=self.unit)
 
-    def to_xnc(self, ctx):
+    def _to_xnc(self, ctx):
         yield from ctx.select_tool(self.tool)
         yield from ctx.route_mode(self.unit, self.x1, self.y1)
         code = 'G02' if self.clockwise else 'G03'
@@ -376,6 +585,7 @@ class Arc(GerberObject):
 
         ctx.set_current_point(self.unit, self.x2, self.y2)
 
+    # internally used to compute Excellon file path length
     def curve_length(self, unit=MM):
         return self.unit.convert_to(unit, math.hypot(self.cx, self.cy) * self.sweep_angle)
 
diff --git a/gerbonara/graphic_primitives.py b/gerbonara/graphic_primitives.py
index 65aa28c..889aa92 100644
--- a/gerbonara/graphic_primitives.py
+++ b/gerbonara/graphic_primitives.py
@@ -201,10 +201,10 @@ class ArcPoly(GraphicPrimitive):
 
     # list of (x : float, y : float) tuples. Describes closed outline, i.e. first and last point are considered
     # connected.
-    outline : [(float,)]
+    outline : list
     # must be either None (all segments are straight lines) or same length as outline.
     # Straight line segments have None entry.
-    arc_centers : [(float,)] = None
+    arc_centers : list = None
 
     @property
     def segments(self):
diff --git a/gerbonara/rs274x.py b/gerbonara/rs274x.py
index 8bd622b..837440f 100644
--- a/gerbonara/rs274x.py
+++ b/gerbonara/rs274x.py
@@ -79,6 +79,9 @@ class GerberFile(CamFile):
             
         return ExcellonFile(objects=new_objs, comments=self.comments)
 
+    def to_gerber(self):
+        return
+
     def merge(self, other):
         """ Merge other GerberFile into this one """
         if other is None:
@@ -222,9 +225,9 @@ class GerberFile(CamFile):
 
     def save(self, filename, settings=None, drop_comments=True):
         with open(filename, 'w', encoding='utf-8') as f: # Encoding is specified as UTF-8 by spec.
-            f.write(self.to_gerber(settings, drop_comments=drop_comments))
+            f.write(self.generate_gerber(settings, drop_comments=drop_comments))
 
-    def to_gerber(self, settings=None, drop_comments=True):
+    def generate_gerber(self, settings=None, drop_comments=True):
         # Use given settings, or use same settings as original file if not given, or use defaults if not imported from a
         # file
         if settings is None:
@@ -245,8 +248,8 @@ class GerberFile(CamFile):
 
     def offset(self, dx=0,  dy=0, unit=MM):
         # TODO round offset to file resolution
-    
-        self.objects = [ obj.with_offset(dx, dy, unit) for obj in self.objects ]
+        for obj in self.objects:
+            obj.with_offset(dx, dy, unit)
 
     def rotate(self, angle:'radian', center=(0,0), unit=MM):
         """ Rotate file contents around given point.
diff --git a/setup.py b/setup.py
index d1a99eb..94b1e56 100644
--- a/setup.py
+++ b/setup.py
@@ -30,7 +30,7 @@ setup(
     name='gerbonara',
     version=version(),
     author='jaseg, XenGi',
-    author_email='contact@gerbonara.jaseg.de',
+    author_email='gerbonara@jaseg.de',
     description='Tools to handle Gerber and Excellon files in Python',
     long_description=long_description(),
     long_description_content_type='text/markdown',