Update API docs

docs/api.rst

@@ -6,8 +6,8 @@ API reference
    :caption: View
    :maxdepth: 1
 
-   api/protocols
    api/view
+   api/model
    api/painters
    api/tools
 
@@ -17,6 +17,7 @@ The central part for Gaphas is the View. That's the class that ensures stuff is
    :caption: Connections
    :maxdepth: 1
 
+   api/handles
    api/connections
    api/variable
 
@@ -28,6 +29,5 @@ One of Gaphas' USP is it's the way it handles connections and the constraint sol
 
    api/matrix
    api/geometry
-   api/decorators
 
 Finally there are classes and modules that make up the building blocks on which Gaphas is built:

docs/api/connections.rst

@@ -1,7 +1,7 @@
 Connections
 ===========
 
-The ``Connections`` class can be used to manage any type of constraint.
+The ``Connections`` class can be used to manage any type of constraint within, and between items.
 
 .. autoclass:: gaphas.connections.Connections
    :members:

docs/api/handles.rst

@@ -0,0 +1,35 @@
+Handles and Ports
+=================
+
+To connect one item to another, you need something to connect, and something to connect to.
+These roles are fulfilled by ``Handle`` and ``Port``.
+
+The Handle is an item you normally see on screen as a small square, eiter green or red.
+Although the actual shape depends on the Painter_ used.
+
+Ports represent the receiving side. A port decides if it wants a connection with a handle.
+If it does, a constraint can be created and this constraint will be managed by a Connections_ instance.
+It is not uncommon to create special ports to suite your application's behavior, whereas Handles are rarely subtyped.
+
+Handle
+------
+
+.. autoclass:: gaphas.connector.Handle
+   :members:
+
+Port
+----
+
+The ``Port`` class. There are two default implementations: ``LinePort`` and ``PointPort``.
+
+.. autoclass:: gaphas.connector.Port
+   :members:
+
+.. autoclass:: gaphas.connector.LinePort
+   :members:
+
+.. autoclass:: gaphas.connector.PointPort
+   :members:
+
+.. _Painter: painters.html#gaphas.painter.HandlePainter
+.. _Connections: connections.html

docs/api/model.rst

@@ -0,0 +1,38 @@
+
+Model
+=====
+
+Protocols
+---------
+
+Although ``gaphas.Canvas`` can be used as a default model, any class that adhere's to the Model protocol can be used as a model.
+
+.. autoclass:: gaphas.view.model.Model
+   :members:
+
+An item should implement these methods, so it can be rendered by the View. Not that painters or tools can require additional methods.
+
+.. autoclass:: gaphas.item.Item
+   :members:
+
+Default implementations
+-----------------------
+
+Canvas
+~~~~~~
+
+The default implementation for a ``Model``, is a class called ``Canvas``.
+
+.. autoclass:: gaphas.canvas.Canvas
+   :members:
+
+Items
+~~~~~
+
+Gaphas provides two default items, an box-like element and a line shape.
+
+.. autoclass:: gaphas.item.Element
+   :members:
+
+.. autoclass:: gaphas.item.Line
+   :members:

docs/api/painters.rst

@@ -3,6 +3,9 @@ Painters
 
 Painters are used to draw the view.
 
+Protocols
+---------
+
 Each painter adheres to the ``Painter`` protocol.
 
 .. autoclass:: gaphas.painter.Painter

docs/api/protocols.rst

@@ -1,18 +0,0 @@
-
-Protocols
-=========
-
-Although ``gaphas.Canvas`` can be used as a default model, any class that adhere's to the Model protocol can be used as a model.
-
-.. autoclass:: gaphas.view.model.Model
-   :members:
-
-An item should implement these methods, so it can be rendered by the View. Not that painters or tools can require additional methods.
-
-.. autoclass:: gaphas.item.Item
-   :members:
-
-The view should support just thise one protocol, which will allow update requests to
-propagate to the view:
-
-.. automethod:: gaphas.view.model.View.request_update

docs/api/tools.rst

@@ -3,7 +3,7 @@ Tools
 
 Tools are used to interact with the view.
 
-Each tool is basically a function that produces a ``Gtk.EventController``.
+Each tool is basically a function that produces a Gtk.EventController_.
 The event controllers are already configured.
 
 .. autofunction:: gaphas.tool.hover_tool
@@ -12,3 +12,6 @@ The event controllers are already configured.
 .. autofunction:: gaphas.tool.rubberband_tool
 .. autofunction:: gaphas.tool.scroll_tool
 .. autofunction:: gaphas.tool.zoom_tool
+
+
+.. _Gtk.EventController: https://lazka.github.io/pgi-docs/#Gtk-3.0/classes/EventController.html

docs/index.rst

@@ -61,6 +61,7 @@ Table of Contents
    quadtree
    table
    tree
+   decorators
 
 .. _Cairo: https://cairographics.org
 .. _Model-View-Controller: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller