doc updates

11 files changed, 228 insertions, 154 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 3177acb3..e1ad76d1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -28,6 +28,8 @@ extensions = ['sphinx.ext.autodoc',
 			  'sphinx.ext.todo', 'sphinx.ext.coverage',
 			  'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
 
+autodoc_default_flags = [ "special-members" ]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/docs/docs.rst b/docs/docs.rst
index dd60ef9f..5996fe0b 100644
--- a/docs/docs.rst
+++ b/docs/docs.rst
@@ -6,11 +6,15 @@ Writing RDFLib Documentation
 
 The docs are generated with Sphinx. 
 
-TODO: Docstrings ... 
+Sphinx makes it very easy to pull in doc-strings from modules, classes, methods, etc. 
+When writing doc-strings, special reST fields can be used to annotate parameters, returntypes, etc. This make for pretty API docs: 
+
+http://sphinx-doc.org/domains.html?highlight=param#info-field-lists
 
 To get N3 and SPARQL syntax highlighting do:
 
 .. code-block:: bash
+
    pip install -e git+git://github.com/gjhiggins/sparql_pygments_lexer.git#egg=SPARQL_Pygments_Lexer
    pip install -e git+git://github.com/gjhiggins/n3_pygments_lexer.git#egg=Notation3_Pygments_Lexer
 
diff --git a/docs/index.rst b/docs/index.rst
index 4c885b16..44cc13f7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -31,9 +31,13 @@ If you never used RDFLib, click through these
    intro_to_graphs
    intro_to_sparql
 
+   RDFLib Examples <apidocs/examples>
+
 In depth
 --------
 
+If you already worked with RDF and need to know the peculiarities of RDFLib, these are for you. 
+
 .. toctree::
    :maxdepth: 1
 
@@ -50,6 +54,8 @@ In depth
 Reference
 ---------
 
+The nitty-gritty details of everything.
+
 Plugins
 ^^^^^^^
 
@@ -91,7 +97,7 @@ For developers
 ==============
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    univrdfstore
    persisting_n3_terms
diff --git a/docs/intro_to_creating_rdf.rst b/docs/intro_to_creating_rdf.rst
index 21a8bc04..7d72f540 100644
--- a/docs/intro_to_creating_rdf.rst
+++ b/docs/intro_to_creating_rdf.rst
@@ -1,5 +1,105 @@
-.. _intro_to_creating_rdf: Creating RDF
+.. _intro_to_creating_rdf: 
+
+====================
+Creating RDF triples
+====================
+
+Creating Nodes
+--------------
+
+RDF is a graph where the nodes are URI references, Blank Nodes or Literals, in RDFLib represented by the classes :class:`~rdflib.term.URIRef`, :class:`~rdflib.term.BNode`, and :class:`~rdflib.term.Literal`. ``URIRefs`` and ``BNodes`` can both be thought of as resources, such a person, a company, a web-site, etc.
+A ``BNode`` is a node where the exact URI is not known.
+``URIRefs`` are also used to represent the properties/predicates in the RDF graph. 
+``Literals`` represent attribute values, such as a name, a date, a number, etc. 
+
+
+Nodes can be created by the constructors of the node classes:: 
+
+   >>> from rdflib import URIRef, BNode, Literal
+   >>> bob = URIRef("http://example.org/people/Bob")
+   >>> linda = BNode() # a GUID is generated
+   >>> name = Literal('Bob') # passing a string
+   >>> age = Literal(24) # passing a python int
+   >>> height = Literal(76.5) # passing a python float
+
+Literals can be created from python objects, these created ``data-typed literals``, for the details on the mapping see :ref:`literals`.
+
+For creating many ``URIRefs`` in the same ``namespace``, i.e. URIs with the same prefix, RDFLib has the :class:`rdflib.namespace.Namespace` class:: 
+
+   >>> from rdflib import Namespace
+   >>> n = Namespace("http://example.org/people/")
+   >>> n.bob
+   rdflib.term.URIRef(u'http://example.org/people/bob') 
+   >>> n.eve
+   rdflib.term.URIRef(u'http://example.org/people/eve')
+
+	
+This is very useful for schemas where all properties and classes have the same URI prefix, RDFLib pre-defines Namespaces for the most common RDF schemas:: 
+
+  >>> from rdflib.namespace import RDF, FOAF 
+  >>> RDF.type
+  rdflib.term.URIRef(u'http://www.w3.org/1999/02/22-rdf-syntax-ns#type')
+  >>> FOAF.knows
+  rdflib.term.URIRef(u'http://xmlns.com/foaf/0.1/knows')
+
+Adding Triples
+--------------
+
+We already saw in :doc:`intro_to_parsing`, how triples can be added with with the :meth:`~rdflib.graph.Graph.parse` function.
+
+Triples can also be added with the :meth:`~rdflib.graph.Graph.add` function: 
+
+.. automethod:: rdflib.graph.Graph.add
+    :noindex:
+
+:meth:`~rdflib.graph.Graph.add` takes a 3-tuple of RDFLib nodes. Try the following with the nodes and namespaces we defined previously:: 
+
+     >>> from rdflib import Graph
+     >>> g = Graph()
+
+     >>> g.add( (bob, RDF.type, FOAF.Person) ) 
+     >>> g.add( (bob, FOAF.name, name) ) 
+     >>> g.add( (bob, FOAF.knows, linda) ) 
+     >>> g.add( (linda, RDF.type, FOAF.Person) ) 
+     >>> g.add( (linda, FOAF.name, Literal('Linda') ) )
+
+     >>> print g.serialize(format='turtle')
+
+outputs: 
+
+.. code-block:: n3
+
+	@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+	@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+	@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+	@prefix xml: <http://www.w3.org/XML/1998/namespace> .
+
+	<http://example.org/people/Bob> a foaf:Person ;
+		foaf:knows [ a foaf:Person ;
+				foaf:name "Linda" ] ;
+		foaf:name "Bob" .
+
+For some properties, only one value per resource makes sense (i.e they are *functional properties*, or have max-cardinality of 1). The :meth:`~rdflib.graph.Graph.set` method is useful for this::
+
+  >>> g.add( ( bob, FOAF.age, Literal(42) ) 
+  >>> print "Bob is ", g.value( bob, FOAF.age ) 
+  Bob is 42
+  
+  >>> g.set( ( bob, age, Literal(43) ) ) # replaces 42 set above
+  >>> print "Bob is now ", g.value( bob, FOAF.age ) 
+  Bob is now 43
+
+(:meth:`rdflib.graph.Graph.value` is the matching query method, it will return a single value for a property, optionally raising an exception if there are more.)
+
+Removing Triples
+^^^^^^^^^^^^^^^^
+
+Similarly, triples can be removed by a call to :meth:`~rdflib.graph.Graph.remove`:
+
+.. automethod:: rdflib.graph.Graph.remove
+    :noindex:
+
+When removing, it is possible to leave parts of the triple unspecified (i.e. passing ``None``), this will remove all matching triples::
+
+   >>> g.remove( (bob, None, None) ) # remove all triples about bob
 
-============================
-Creating RDF with RDFLib
-============================
diff --git a/docs/intro_to_graphs.rst b/docs/intro_to_graphs.rst
index 21031dab..eabd55a3 100644
--- a/docs/intro_to_graphs.rst
+++ b/docs/intro_to_graphs.rst
@@ -1,24 +1,76 @@
 .. _rdflib_graph: Navigating Graphs
 
-============================
-Navigating RDFLib Graphs
-============================
-.. module rdflib.graph
+=================
+Navigating Graphs
+=================
 
-The :class:`~rdflib.graph.Graph` class
---------------------------------------
-.. autoclass:: rdflib.graph.Graph
-    :members:
-    :noindex:
+An RDF Graph is a set of RDF triples, and we try to mirror exactly this in RDFLib, and the graph tries to emulate a container type. 
+
+Graphs as Iterators
+-------------------
+
+RDFLib graphs override :meth:`~rdflib.graph.Graph.__iter__` in order to support iteration over the contained triples:
+
+.. code-block:: python
+
+    for subject,predicate,obj_ in someGraph:
+       assert (subject,predicate,obj_) in someGraph, "Iterator / Container Protocols are Broken!!"
+
+Set Operations on RDFLib Graphs 
+-------------------------------
+
+:meth:`~rdflib.graph.Graph.__iadd__` and :meth:`~rdflib.graph.Graph.__isub__` are overridden to support adding and subtracting Graphs to/from each other (in place):
+
+* G1 += G1
+* G2 -= G2
 
-.. autoclass:: rdflib.graph.ConjunctiveGraph
+.. warning: If you are using blank-nodes set-operations on graphs may or may not do what you want, 
+
+Basic Triple Matching
+---------------------
+
+RDFLib graphs support basic triple pattern matching with a :meth:`~rdflib.graph.Graph.triples` function.
+
+.. automethod:: rdflib.graph.Graph.triples
     :noindex:
 
-.. autoclass:: rdflib.graph.Dataset
-    :members:
+This function is a generator of triples that match the pattern given by the arguments.  The arguments of these are RDF terms that restrict the triples that are returned.  Terms that are :data:`None` are treated as a wildcard.
+
+
+
+
+
+:class:`~rdflib.graph.Graph` methods for accessing triples
+-----------------------------------------------------------
+
+.. automethod:: rdflib.graph.Graph.add
+    :noindex:
+.. automethod:: rdflib.graph.Graph.set
+    :noindex:
+.. automethod:: rdflib.graph.Graph.label
+    :noindex:
+.. automethod:: rdflib.graph.Graph.preferredLabel
+    :noindex:
+.. automethod:: rdflib.graph.Graph.remove
+    :noindex:
+.. automethod:: rdflib.graph.Graph.triples
+    :noindex:
+.. automethod:: rdflib.graph.Graph.value
+    :noindex:
+.. automethod:: rdflib.graph.Graph.subjects
+    :noindex:
+.. automethod:: rdflib.graph.Graph.objects
+    :noindex:
+.. automethod:: rdflib.graph.Graph.predicates
+    :noindex:
+.. automethod:: rdflib.graph.Graph.subject_objects
+    :noindex:
+.. automethod:: rdflib.graph.Graph.subject_predicates
+    :noindex:
+.. automethod:: rdflib.graph.Graph.predicate_objects
     :noindex:
 
-Working with RDFLib graphs
--------------------------------
-.. automodule:: rdflib.graph
+
+
+
 
diff --git a/docs/intro_to_parsing.rst b/docs/intro_to_parsing.rst
index df79cd44..7a585aee 100644
--- a/docs/intro_to_parsing.rst
+++ b/docs/intro_to_parsing.rst
@@ -1,19 +1,22 @@
-.. _intro_to_parsing: Parsing RDF
+.. _intro_to_parsing: 
 
-==================================
-Parsing RDF into RDFLib graphs
-==================================
+======================
+Loading and saving RDF
+======================
 
 Reading an NT file
 -------------------
 
-RDF data has various syntaxes (``xml``, ``n3``, ``ntriples``, ``trix``, etc) that you might want to read. The simplest format is ``ntriples``. Create the file :file:`demo.nt` in the current directory with these two lines:
+RDF data has various syntaxes (``xml``, ``n3``, ``ntriples``, ``trix``, etc) that you might want to read. The simplest format is ``ntriples``, a line-based format. Create the file :file:`demo.nt` in the current directory with these two lines:
 
 .. code-block:: n3
 
     <http://bigasterisk.com/foaf.rdf#drewp> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
     <http://bigasterisk.com/foaf.rdf#drewp> <http://example.com/says> "Hello world" .
 
+You need to tell RDFLib what format to parse, use the ``format`` keyword-parameter to :meth:`~rdflib.graph.Graph.parse`, you can pass either a mime-type or the name (a :doc:`list of available parsers <plugin_parsers>` is available).
+If you are not sure what format your file will be, you can use :func:`rdflib.util.guess_format` which will guess based on the file extension. 
+
 In an interactive python interpreter, try this:
 
 .. code-block:: pycon
@@ -50,101 +53,5 @@ Reading graphs from the net is just as easy:
 
 The format defaults to ``xml``, which is the common format for .rdf files you'll find on the net.
 
-Graphs as Iterators
--------------------
-
-RDFLib graphs also override :meth:`__iter__` in order to support iteration over the contained triples:
-
-.. code-block:: python
-
-    for subject,predicate,obj_ in someGraph:
-       assert (subject,predicate,obj_) in someGraph, "Iterator / Container Protocols are Broken!!"
-
-Set Operations on RDFLib Graphs 
--------------------------------
-
-:meth:`__iadd__` and :meth:`__isub__` are overridden to support adding and subtracting Graphs to/from each other (in place):
-
-* G1 += G1
-* G2 -= G2
-
-Basic Triple Matching
----------------------
-
-RDFLib graphs support basic triple pattern matching with a :meth:`triples` function.
-
-.. automethod:: rdflib.graph.Graph.triples
-    :noindex:
-
-This function is a generator of triples that match the pattern given by the arguments.  The arguments of these are RDF terms that restrict the triples that are returned.  Terms that are :data:`None` are treated as a wildcard.
-
-Managing Triples
-----------------
-
-Adding Triples
-^^^^^^^^^^^^^^
-Triples can be added either of two ways:
-
-Triples can be added with with the :meth:`parse` function.
-
-.. automethod:: rdflib.graph.Graph.parse
-    :noindex:
-
-The first argument can be a *source* of many kinds, but the most common is the serialization (in various formats: RDF/XML, Notation 3, NTriples of an RDF graph as a string.  The ``format`` parameter is one of ``n3``, ``xml``, or ``ntriples``.  ``publicID`` is the name of the graph into which the RDF serialization will be parsed.
-
-Triples can also be added with the :meth:`add` function: 
-
-.. automethod:: rdflib.graph.Graph.add
-    :noindex:
-
-Removing Triples
-^^^^^^^^^^^^^^^^
-
-Similarly, triples can be removed by a call to :meth:`remove`:
-
-.. automethod:: rdflib.graph.Graph.remove
-    :noindex:
-
-
-
-.. module:: rdflib.graph
-
-:class:`~rdflib.graph.Graph` methods for accessing triples
------------------------------------------------------------
-
-.. automethod:: rdflib.graph.Graph.add
-    :noindex:
-.. automethod:: rdflib.graph.Graph.set
-    :noindex:
-.. automethod:: rdflib.graph.Graph.label
-    :noindex:
-.. automethod:: rdflib.graph.Graph.preferredLabel
-    :noindex:
-.. automethod:: rdflib.graph.Graph.remove
-    :noindex:
-.. automethod:: rdflib.graph.Graph.triples
-    :noindex:
-.. automethod:: rdflib.graph.Graph.value
-    :noindex:
-.. automethod:: rdflib.graph.Graph.subjects
-    :noindex:
-.. automethod:: rdflib.graph.Graph.objects
-    :noindex:
-.. automethod:: rdflib.graph.Graph.predicates
-    :noindex:
-.. automethod:: rdflib.graph.Graph.subject_objects
-    :noindex:
-.. automethod:: rdflib.graph.Graph.subject_predicates
-    :noindex:
-.. automethod:: rdflib.graph.Graph.predicate_objects
-    :noindex:
-
-
-Full documentation
-------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   intro_to_graphs
+RDFLib will also happily read RDF from any file-like object, i.e. anything with a ``.read`` method. 
 
diff --git a/docs/intro_to_sparql.rst b/docs/intro_to_sparql.rst
index 552c9932..b096b409 100644
--- a/docs/intro_to_sparql.rst
+++ b/docs/intro_to_sparql.rst
@@ -1,8 +1,8 @@
-.. _intro_to_using_sparql: Querying with SPARQL
+.. _intro_to_using_sparql: 
 
-============================
-SPARQL Queries in RDFLib
-============================
+====================
+Querying with SPARQL
+====================
 
 Create an Rdflib Graph
 ^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/plugin_parsers.rst b/docs/plugin_parsers.rst
index 235e6dd4..e114958d 100644
--- a/docs/plugin_parsers.rst
+++ b/docs/plugin_parsers.rst
@@ -5,32 +5,32 @@ Plugin parsers
 ==============
 
 These serializers are available in default RDFLib, you can use them by 
-passing the name to graph's :meth:`~rdflib.graph.Graph.parse` method: 
-
-.. code-block:: python
+passing the name to graph's :meth:`~rdflib.graph.Graph.parse` method:: 
 
 	graph.parse(my_url, format='n3')
 
 The ``html`` parser will auto-detect RDFa, HTurtle or Microdata.
 
-===================== ====================================================================
-Name                  Class                                                               
-===================== ====================================================================
-application/rdf+xml   :class:`~rdflib.plugins.parsers.rdfxml.RDFXMLParser`
-application/svg+xml   :class:`~rdflib.plugins.parsers.structureddata.RDFaParser`
-application/xhtml+xml :class:`~rdflib.plugins.parsers.structureddata.RDFaParser`
-html                  :class:`~rdflib.plugins.parsers.structureddata.StructuredDataParser`
-hturtle               :class:`~rdflib.plugins.parsers.hturtle.HTurtleParser`
-mdata                 :class:`~rdflib.plugins.parsers.structureddata.MicrodataParser`
-microdata             :class:`~rdflib.plugins.parsers.structureddata.MicrodataParser`
-n3                    :class:`~rdflib.plugins.parsers.notation3.N3Parser`
-nquads                :class:`~rdflib.plugins.parsers.nquads.NQuadsParser`
-nt                    :class:`~rdflib.plugins.parsers.nt.NTParser`
-rdfa                  :class:`~rdflib.plugins.parsers.structureddata.RDFaParser`
-rdfa1.0               :class:`~rdflib.plugins.parsers.structureddata.RDFa10Parser`
-rdfa1.1               :class:`~rdflib.plugins.parsers.structureddata.RDFaParser`
-text/html             :class:`~rdflib.plugins.parsers.structureddata.StructuredDataParser`
-trix                  :class:`~rdflib.plugins.parsers.trix.TriXParser`
-turtle                :class:`~rdflib.plugins.parsers.notation3.TurtleParser`
-xml                   :class:`~rdflib.plugins.parsers.rdfxml.RDFXMLParser`
-===================== ====================================================================
+It is also possible to pass a mime-type for the ``format`` parameter::
+    
+  graph.parse(my_url, format='application/rdf+xml')
+
+If you are not sure what format your file will be, you can use :func:`rdflib.util.guess_format` which will guess based on the file extension. 
+
+========= ====================================================================
+Name      Class                                                               
+========= ====================================================================
+html      :class:`~rdflib.plugins.parsers.structureddata.StructuredDataParser`
+hturtle   :class:`~rdflib.plugins.parsers.hturtle.HTurtleParser`
+mdata     :class:`~rdflib.plugins.parsers.structureddata.MicrodataParser`
+microdata :class:`~rdflib.plugins.parsers.structureddata.MicrodataParser`
+n3        :class:`~rdflib.plugins.parsers.notation3.N3Parser`
+nquads    :class:`~rdflib.plugins.parsers.nquads.NQuadsParser`
+nt        :class:`~rdflib.plugins.parsers.nt.NTParser`
+rdfa      :class:`~rdflib.plugins.parsers.structureddata.RDFaParser`
+rdfa1.0   :class:`~rdflib.plugins.parsers.structureddata.RDFa10Parser`
+rdfa1.1   :class:`~rdflib.plugins.parsers.structureddata.RDFaParser`
+trix      :class:`~rdflib.plugins.parsers.trix.TriXParser`
+turtle    :class:`~rdflib.plugins.parsers.notation3.TurtleParser`
+xml       :class:`~rdflib.plugins.parsers.rdfxml.RDFXMLParser`
+========= ====================================================================
diff --git a/docs/plugin_serializers.rst b/docs/plugin_serializers.rst
index 41be2fe1..0aedd566 100644
--- a/docs/plugin_serializers.rst
+++ b/docs/plugin_serializers.rst
@@ -5,12 +5,13 @@ Plugin serializers
 ==================
 
 These serializers are available in default RDFLib, you can use them by 
-passing the name to a graph's :meth:`~rdflib.graph.Graph.serialize` method: 
-
-.. code-block:: python
+passing the name to a graph's :meth:`~rdflib.graph.Graph.serialize` method::
 
 	print graph.serialize(format='n3')
 
+It is also possible to pass a mime-type for the ``format`` parameter::
+    
+  graph.serialize(my_url, format='application/rdf+xml')
 
 ========== ===============================================================
 Name       Class                                                          
diff --git a/docs/plugintable.py b/docs/plugintable.py
index cc7ace38..e982647d 100644
--- a/docs/plugintable.py
+++ b/docs/plugintable.py
@@ -12,6 +12,7 @@ cls = sys.argv[1]
 p = {}
 
 for (name, kind), plugin in _plugins.items(): 
+    if "/" in name: continue # skip duplicate entries for mimetypes
     if cls == kind.__name__: 
         p[name]="%s.%s"%(plugin.module_path, plugin.class_name)
 
diff --git a/docs/rdf_terms.rst b/docs/rdf_terms.rst
index 9ab12a7d..5fe883d5 100644
--- a/docs/rdf_terms.rst
+++ b/docs/rdf_terms.rst
@@ -64,6 +64,7 @@ URIRefs
     u'<http://example.com>'
 
 
+.. literals:
 Literals
 ========