Reorganise documentation - phase 1

25 files changed, 287 insertions, 159 deletions

diff --git a/docs/modules/collection.rst b/docs/modules/collection.rst
new file mode 100644
index 00000000..94f63e9e
--- /dev/null
+++ b/docs/modules/collection.rst
@@ -0,0 +1,11 @@
+.. _others: Other modules
+
+
+=============
+Collection
+=============
+
+.. automodule:: rdflib.collection
+.. :noindex:
+.. autoclass:: rdflib.collection.Collection
+    :members:
diff --git a/docs/modules/events.rst b/docs/modules/events.rst
new file mode 100644
index 00000000..5e6abed6
--- /dev/null
+++ b/docs/modules/events.rst
@@ -0,0 +1,12 @@
+.. _rdflib.events: Event registration
+
+======
+Events
+======
+.. automodule:: rdflib.events
+.. :noindex:
+.. autoclass:: rdflib.events.Event
+    :members:
+.. autoclass:: rdflib.events.Dispatcher
+    :members:
+
diff --git a/docs/modules/graphs/conjunctive_graph.rst b/docs/modules/graphs/conjunctive_graph.rst
index a0eefdb2..416f8233 100644
--- a/docs/modules/graphs/conjunctive_graph.rst
+++ b/docs/modules/graphs/conjunctive_graph.rst
@@ -1,15 +1,23 @@
-:mod:`rdflib.Graph.ConjunctiveGraph` -- ConjunctiveGraph class definition
-=========================================================================
+:mod:`rdflib.Graph.ConjunctiveGraph` -- ConjunctiveGraph
+========================================================
 
-=================
-Conjunctive Graph
-=================
+.. autoclass:: rdflib.graph.ConjunctiveGraph
+    :members:
 
-.. automodule:: rdflib.graph
+Modelling notes
+----------------
+This refers to the 'top-level' Graph. It is the aggregation of all the contexts within it and is also the appropriate, absolute boundary for closed world assumptions / models. This distinction is the low-hanging fruit of RDF along the path to the semantic web and most of its value is in (corporate/enterprise) real-world problems:
 
+There are at least two situations where the closed world assumption is used. The first is where it is assumed that a knowledge base contains all relevant facts. This is common in corporate databases. That is, the information it contains is assumed to be complete
+
+From a store perspective, closed world assumptions also provide the benefit of better query response times due to the explicit closed world boundaries. Closed world boundaries can be made transparent by federated queries that assume each ConjunctiveGraph is a section of a larger, unbounded universe. So a closed world assumption does not preclude you from an open world assumption.
+
+For the sake of persistence, Conjunctive Graphs must be distinguished by identifiers (that may not necessarily be RDF identifiers or may be an RDF identifier normalized - SHA1/MD5 perhaps - for database naming purposes ) which could be referenced to indicate conjunctive queries (queries made across the entire conjunctive graph) or appear as nodes in asserted statements. In this latter case, such statements could be interpreted as being made about the entire 'known' universe. For example:
+
+<urn:uuid:conjunctive-graph-foo> rdf:type :ConjunctiveGraph
+
+<urn:uuid:conjunctive-graph-foo> rdf:type log:Truth
+
+<urn:uuid:conjunctive-graph-foo> :persistedBy :MySQL
 
-Module Contents
----------------
 
-.. autoclass:: rdflib.graph.ConjunctiveGraph
-    :members:
diff --git a/docs/modules/graphs/graph.rst b/docs/modules/graphs/graph.rst
index c4d314f9..6734628a 100644
--- a/docs/modules/graphs/graph.rst
+++ b/docs/modules/graphs/graph.rst
@@ -1,12 +1,7 @@
-:mod:`rdflib.graph.Graph` -- Graph class definition
-===================================================
+:mod:`rdflib.graph.Graph` -- Graph
+==================================
 
-=====
-Graph
-=====
-
-Module Contents
----------------
 
 .. autoclass:: rdflib.graph.Graph
     :members:
+
diff --git a/docs/modules/graphs/index.rst b/docs/modules/graphs/index.rst
index 59e1829a..5cc8a8f7 100644
--- a/docs/modules/graphs/index.rst
+++ b/docs/modules/graphs/index.rst
@@ -10,13 +10,42 @@ RDFLib defines the following kinds of Graphs:
 * QuotedGraph(**store**, **identifier**)
 * ConjunctiveGraph(**store**, **default_identifier** = None)
 
+Graph
+-----
+An RDF graph is a set of RDF triples.
+
+The set of nodes of an RDF graph is the set of subjects and objects of triples in the graph.
+
+.. toctree::
+    :maxdepth: 2
+
+    graph
+
+
+Conjunctive Graph
+-----------------
+
 A Conjunctive Graph is the most relevant collection of graphs that are considered to be the boundary for closed world assumptions.  This boundary is equivalent to that of the store instance (which is itself uniquely identified and distinct from other instances of :class:`Store` that signify other Conjunctive Graphs).  It is equivalent to all the named graphs within it and associated with a ``_default_`` graph which is automatically assigned a :class:`BNode` for an identifier - if one isn't given.  
 
-.. automodule:: rdflib.graph
+.. toctree::
+    :maxdepth: 1
+
+    conjunctive_graph
+
+
+Quoted graph
+------------
+
+The notion of an RDF graph [14] is extended to include the concept of a formula node. A formula node may occur wherever any other kind of node can appear. Associated with a formula node is an RDF graph that is completely disjoint from all other graphs; i.e. has no nodes in common with any other graph. (It may contain the same labels as other RDF graphs; because this is, by definition, a separate graph, considerations of tidiness do not apply between the graph at a formula node and any other graph.)
+
+This is intended to map the idea of "{ N3-expression }" that is used by N3 into an RDF graph upon which RDF semantics is defined.
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
+
+    quoted_graph
 
-   graph
-   conjunctive_graph
-   ../nodes/quoted_graph
\ No newline at end of file
+Working with graphs
+-------------------
+
+.. automodule:: rdflib.graph
diff --git a/docs/modules/nodes/quoted_graph.rst b/docs/modules/graphs/quoted_graph.rst
index f5cd4499..eb739ec3 100644
--- a/docs/modules/nodes/quoted_graph.rst
+++ b/docs/modules/graphs/quoted_graph.rst
@@ -1,5 +1,5 @@
-:mod:`rdflib.graph.QuotedGraph` -- Quoted graphs
-================================================
+:mod:`rdflib.graph.QuotedGraph` -- Quoted graph
+===============================================
 
 RDFLib graphs support an additional extension of RDF semantics for formulae. For the academically inclined, Graham Kyles `formal extension`__ is probably a good read.
 
@@ -7,7 +7,5 @@ RDFLib graphs support an additional extension of RDF semantics for formulae. For
 
 Formulae are represented formally by the :class:`~rdflib.graph.QuotedGraph` class and are disjoint from regular RDF graphs in that their statements are quoted.
 
-Module Contents
----------------
-
 .. autoclass:: rdflib.graph.QuotedGraph
+    :members:
diff --git a/docs/modules/index.rst b/docs/modules/index.rst
index 75eaec1c..8e12334e 100644
--- a/docs/modules/index.rst
+++ b/docs/modules/index.rst
@@ -4,12 +4,19 @@
 Modules
 =======
 
-Contents:
-=========
-
 .. toctree::
     :maxdepth: 3
 
-    nodes/index
+    collection
+    events
     graphs/index
-    others
+    namespace
+    node
+    parser
+    resource
+    result
+    serializer
+    statement
+    store
+    term
+    util
diff --git a/docs/modules/namespace.rst b/docs/modules/namespace.rst
new file mode 100644
index 00000000..85661041
--- /dev/null
+++ b/docs/modules/namespace.rst
@@ -0,0 +1,16 @@
+.. _rdflib.namespace: Namespace utils
+
+=========
+Namespace
+=========
+
+.. automodule:: rdflib.namespace
+    :members:
+
+.. autoclass:: rdflib.namespace.NamespaceManager
+    :members:
+
+.. autoclass:: rdflib.namespace.Namespace
+    :members:
+
+.. autofunction:: rdflib.namespace.split_uri
diff --git a/docs/modules/node.rst b/docs/modules/node.rst
new file mode 100644
index 00000000..e0ee12b7
--- /dev/null
+++ b/docs/modules/node.rst
@@ -0,0 +1,40 @@
+.. _nodes:
+
+=======
+Nodes
+=======
+
+Nodes are a subset of the Terms that the underlying store actually persists.
+The set of such Terms depends on whether or not the store is formula-aware. 
+Stores that aren't formula-aware would only persist those terms core to the 
+RDF Model, and those that are formula-aware would be able to persist the N3 
+extensions as well. However, utility terms that only serve the purpose for 
+matching nodes by term-patterns probably will only be terms and not nodes.
+
+The set of nodes of an RDF graph is the set of subjects and objects of triples in the graph.
+
+The RDFLib classes listed below model RDF `terms`__ in a graph and inherit from a common `Identifier`_ class, which extends Python unicode.  Instances of these are nodes in an RDF graph.
+
+.. automodule:: rdflib.term
+
+.. autoclass:: rdflib.term.Node
+    :members:
+
+.. autoclass:: rdflib.term.Identifier
+    :members:
+
+.. autoclass:: rdflib.term.BNode
+    :members:
+
+.. autoclass:: rdflib.term.URIRef
+    :members:
+
+.. autoclass:: rdflib.term.Literal
+    :members:
+
+.. autoclass:: rdflib.term.Variable
+    :members:
+
+
+.. __: univrdfstore.html#Terms
+.. _Identifier: http://www.w3.org/2002/07/rdf-identifer-terminology/
diff --git a/docs/modules/nodes/bnode.rst b/docs/modules/nodes/bnode.rst
deleted file mode 100644
index 587f31a6..00000000
--- a/docs/modules/nodes/bnode.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-:mod:`rdflib.term.BNode` -- RDF blank node functions
-====================================================
-
-.. automodule:: rdflib.term
-
-Module Contents
----------------
-
-.. autoclass:: rdflib.term.BNode
-    :members:
diff --git a/docs/modules/nodes/identifier.rst b/docs/modules/nodes/identifier.rst
deleted file mode 100644
index bbd0b108..00000000
--- a/docs/modules/nodes/identifier.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-:mod:`rdflib.term.Identifier` -- Identifier class definition
-============================================================
-
-.. automodule:: rdflib.term
-
-Module Contents
----------------
-
-.. autoclass:: rdflib.term.Identifier
-    :members:
diff --git a/docs/modules/nodes/index.rst b/docs/modules/nodes/index.rst
deleted file mode 100644
index b9fa6a15..00000000
--- a/docs/modules/nodes/index.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-.. _nodes:
-
-=======
-Nodes
-=======
-
-The RDFLib classes listed below model RDF `terms`__ in a graph and inherit from a common `Identifier`_ class, which extends Python unicode.  Instances of these are nodes in an RDF graph.
-
-.. toctree::
-   :maxdepth: 2
-
-   node
-   identifier
-   bnode
-   uriref
-   literal
-   variable
-   quoted_graph
-
-
-.. __: univrdfstore.html#Terms
-.. _Identifier: http://www.w3.org/2002/07/rdf-identifer-terminology/
diff --git a/docs/modules/nodes/literal.rst b/docs/modules/nodes/literal.rst
deleted file mode 100644
index ad408b9a..00000000
--- a/docs/modules/nodes/literal.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-:mod:`rdflib.term.Literal` -- Literal class definition
-======================================================
-
-.. automodule:: rdflib.term
-
-Module Contents
----------------
-
-.. autoclass:: rdflib.term.Literal
-    :members:
diff --git a/docs/modules/nodes/node.rst b/docs/modules/nodes/node.rst
deleted file mode 100644
index 90fd2c5d..00000000
--- a/docs/modules/nodes/node.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-:mod:`rdflib.term.Node` -- Node class definition
-================================================
-
-.. automodule:: rdflib.term
-
-Module Contents
----------------
-
-.. autoclass:: rdflib.term.Node
-    :members:
diff --git a/docs/modules/nodes/uriref.rst b/docs/modules/nodes/uriref.rst
deleted file mode 100644
index 672d2b54..00000000
--- a/docs/modules/nodes/uriref.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-:mod:`rdflib.term.URIRef` -- URIRef class definition
-====================================================
-
-.. automodule:: rdflib.term
-
-
-
-Module Contents
----------------
-
-.. autoclass:: rdflib.term.URIRef
-    :members:
diff --git a/docs/modules/nodes/variable.rst b/docs/modules/nodes/variable.rst
deleted file mode 100644
index 651c9a36..00000000
--- a/docs/modules/nodes/variable.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-:mod:`rdflib.term.Variable` -- Variable class definition
-========================================================
-
-.. automodule:: rdflib.term
-
-Module Contents
----------------
-
-.. autoclass:: rdflib.term.Variable
diff --git a/docs/modules/others.rst b/docs/modules/others.rst
deleted file mode 100644
index f4228373..00000000
--- a/docs/modules/others.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-.. _others: Other modules
-
-
-=============
-Other modules
-=============
-
-Collection
-----------
-.. automodule:: rdflib.collection
-.. :noindex:
-.. autoclass:: rdflib.collection.Collection
-    :members:
-
-Events
-------
-.. automodule:: rdflib.events
-.. :noindex:
-.. autoclass:: rdflib.events.Event
-    :members:
-.. autoclass:: rdflib.events.Dispatcher
-    :members:
-
-Result
-------
-.. automodule:: rdflib.query
-.. :noindex:
-.. autoclass:: rdflib.query.Result
-    :members:
-
-Statement
----------
-.. automodule:: rdflib.term
-.. :noindex:
-.. autoclass:: rdflib.term.Statement
-.. automethod:: rdflib.term.Statement.__new__
-.. automethod:: rdflib.term.Statement.__reduce__
-
-Store
------
-.. automodule:: rdflib.store
-.. :noindex:
-
diff --git a/docs/modules/parser.rst b/docs/modules/parser.rst
new file mode 100644
index 00000000..b70be5e4
--- /dev/null
+++ b/docs/modules/parser.rst
@@ -0,0 +1,26 @@
+.. _rdflib.parser: Parser
+
+
+=============
+Parser
+=============
+
+.. automodule:: rdflib.parser
+.. :noindex:
+.. autofunction:: rdflib.parser.create_input_source
+
+.. autoclass:: rdflib.parser.Parser
+    :members:
+
+.. autoclass:: rdflib.parser.InputSource
+    :members:
+
+.. autoclass:: rdflib.parser.StringInputSource
+    :members:
+
+.. autoclass:: rdflib.parser.URLInputSource
+    :members:
+
+.. autoclass:: rdflib.parser.FileInputSource
+    :members:
+
diff --git a/docs/modules/resource.rst b/docs/modules/resource.rst
new file mode 100644
index 00000000..848d47eb
--- /dev/null
+++ b/docs/modules/resource.rst
@@ -0,0 +1,7 @@
+.. _resource:
+
+Resource
+--------
+.. automodule:: rdflib.resource
+.. :noindex:
+
diff --git a/docs/modules/result.rst b/docs/modules/result.rst
new file mode 100644
index 00000000..aa59e7cb
--- /dev/null
+++ b/docs/modules/result.rst
@@ -0,0 +1,10 @@
+.. rdflib.query.result: Result
+
+======
+Result
+======
+.. automodule:: rdflib.query
+.. :noindex:
+.. autoclass:: rdflib.query.Result
+    :members:
+
diff --git a/docs/modules/serializer.rst b/docs/modules/serializer.rst
new file mode 100644
index 00000000..038b64ff
--- /dev/null
+++ b/docs/modules/serializer.rst
@@ -0,0 +1,12 @@
+.. rdflib.serializer: Serializer
+
+===========
+Serializer
+===========
+
+.. automodule:: rdflib.serializer
+.. :noindex:
+.. autoclass:: rdflib.serializer.Serializer
+   :members:
+
+
diff --git a/docs/modules/statement.rst b/docs/modules/statement.rst
new file mode 100644
index 00000000..63879075
--- /dev/null
+++ b/docs/modules/statement.rst
@@ -0,0 +1,13 @@
+.. _rdflib.statement: Other modules
+
+=========
+Statement
+=========
+
+.. currentmodule:: rdflib.term
+.. :noindex:
+.. autoclass:: rdflib.term.Statement
+.. automethod:: rdflib.term.Statement.__new__
+.. automethod:: rdflib.term.Statement.__reduce__
+
+
diff --git a/docs/modules/store.rst b/docs/modules/store.rst
new file mode 100644
index 00000000..039466dd
--- /dev/null
+++ b/docs/modules/store.rst
@@ -0,0 +1,8 @@
+.. _rdflib.store: Other modules
+
+
+Store
+-----
+.. automodule:: rdflib.store
+.. :noindex:
+
diff --git a/docs/modules/term.rst b/docs/modules/term.rst
new file mode 100644
index 00000000..986c0724
--- /dev/null
+++ b/docs/modules/term.rst
@@ -0,0 +1,24 @@
+.. _rdflib.term: Terms
+
+=========
+Term
+=========
+
+.. currentmodule:: rdflib.term
+.. :noindex:
+.. automodule:: rdflib.term
+    :members:
+    :noindex:
+
+.. currentmodule:: rdflib.term
+.. _Seq:
+.. autoclass:: rdflib.graph.Seq
+    :members:
+
+.. _QuotedGraph:
+.. autoclass:: rdflib.graph.QuotedGraph
+    :noindex:
+
+.. _ReadOnlyGraphAggregate:
+.. autoclass:: rdflib.graph.ReadOnlyGraphAggregate
+    :noindex:
diff --git a/docs/modules/util.rst b/docs/modules/util.rst
new file mode 100644
index 00000000..6eb9c32a
--- /dev/null
+++ b/docs/modules/util.rst
@@ -0,0 +1,38 @@
+.. _rdflib.util: Utilities
+
+=========
+Utilities
+=========
+
+.. currentmodule:: rdflib.util
+
+Miscellaneous utilities
+-----------------------
+
+.. autofunction:: rdflib.util.list2set
+.. autofunction:: rdflib.util.first
+.. autofunction:: rdflib.util.uniq
+.. autofunction:: rdflib.util.more_than
+
+Term characterisation and generation
+-------------------------------------
+
+.. autofunction:: rdflib.util.to_term
+.. autofunction:: rdflib.util.from_n3
+
+
+Statement and component type checkers
+-------------------------------------
+
+.. autofunction:: rdflib.util.check_context
+.. autofunction:: rdflib.util.check_subject
+.. autofunction:: rdflib.util.check_predicate
+.. autofunction:: rdflib.util.check_object
+.. autofunction:: rdflib.util.check_statement
+.. autofunction:: rdflib.util.check_pattern
+
+Date/time utilities
+-------------------
+
+.. autofunction:: rdflib.util.date_time
+.. autofunction:: rdflib.util.parse_date_time