Add usage example in docs; add doc page for discovery.

docs/discovery.rst

@@ -0,0 +1,72 @@
+Resource Discovery & Query
+==========================
+
+LAKEsuperior offers several way to programmatically discover resources and
+data.
+
+LDP Traversal
+-------------
+
+The method compatible with the standard Fedora implementation and other LDP
+servers is to simply traverse the LDP tree. While this offers the broadest
+compatibility, it is quite expensive for the client, the server and the
+developer.
+
+For this method, please consult the dedicated `LDP specifications
+<https://www.w3.org/TR/ldp/>`__ and `Fedora API specs
+<https://wiki.duraspace.org/display/FEDORA4x/RESTful+HTTP+API+-+Containers>`__.
+
+SPARQL Query
+------------
+
+A `SPARQL <https://www.w3.org/TR/sparql11-query/>`__ endpoint is available in
+LAKEsuperior both as an API and a Web UI.
+
+.. figure:: assets/lsup_sparql_query_ui.png
+   :alt: LAKEsuperior SPARQL Query Window
+
+   LAKEsuperior SPARQL Query Window
+
+The UI is based on `YasGUI <http://yasgui.org/>`__.
+
+Note that:
+
+#. The SPARQL endpoint only supports the SPARQL 1.1 Query language.
+   SPARQL updates are not, and will not be, supported.
+#. The LAKEshore data model has an added layer of structure that is not exposed
+   through the LDP layer. The SPARQL endpoint exposes this low-level structure
+   and it is beneficial to understand its layout. See :doc:`model` for details
+   in this regard.
+#. The underlying RDF structure is mostly in the RDF named graphs. Querying
+   only triples will give a quite uncluttered view of the data, as close to the
+   LDP representation as possible.
+
+SPARQL Caveats
+~~~~~~~~~~~~~~
+
+The SPARQL query facility has not yet been tested thoroughly. the RDFLib
+implementation that it is based upon can be quite efficient for certain
+queries but has some downsides. For example, do **not** attempt the following
+query in a graph with more than a few thousands resources::
+
+    SELECT ?s {
+      GRAPH ?g {
+        <info:fcres/my-uid> ?p ?o .
+      }
+    }
+
+What the RDFLib implementation does is going over every single graph in the
+repository and perform the ``?s ?p ?o`` query on each of them. Since
+LAKEsuperior creates several graphs per resource, this can run for a very long
+time in any decently sized data set.
+
+The solution to this is either to omit the graph query, or use a term search,
+or a native Python method if applicable.
+
+Term Search
+-----------
+
+This feature has not yet been implemented. It is meant to provide a discovery
+tool based on simple term match, and possibly comparison. It should be more
+efficient and predictable than SPARQL.
+

docs/index.rst

@@ -30,6 +30,7 @@ Indices and tables
    :maxdepth: 3
    :caption: User Reference
 
+    Discovery & query <discovery>
     Divergences from Fedora 4 <fcrepo4_deltas>
     Messaging <messaging>
     Migration Guide <migration>

docs/usage.rst

@@ -114,4 +114,80 @@ Immediately forget a resource
 Python API
 ----------
 
-**TODO**
+Set up the environment
+~~~~~~~~~~~~~~~~~~~~~~
+
+Before using the API, either do::
+
+    >>> import lakesuperior.env_setup
+
+Or, to specify an alternative configuration::
+
+    >>> from lakesuperior.config_parser import parse_config
+    >>> from lakesuperior.globals import AppGlobals
+    >>> env.config, test_config = parse_config('/my/custom/config_dir')
+    Reading configuration at /my/custom/config_dir
+    >>> env.app_globals = AppGlobals(env.config)
+
+Create and replace resources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Providing a serialized RDF stream::
+
+    >>> from lakesuperior.api import resource as rsrc_api
+    >>> from io import BytesIO
+    >>> from lakesuperior.dictionaries.namespaces import ns_collection as nsc
+    >>> uid = '/rsrc_from_stream'
+    >>> uri = nsc['fcres'][uid]
+    >>> stream = BytesIO(b'<> a <http://ex.org/type#A> .')
+    >>> rsrc_api.create_or_replace(uid, stream=stream, mimetype='text/turtle')
+    '_create_'
+
+
+Providng a Graph object::
+
+    >>> from rdflib import Graph, URIRef
+    >>> uid = '/rsrc_from_graph'
+    >>> gr = Graph().parse(data='<> a <http://ex.org/type#A> .',
+    ...     format='text/turtle', publicID=nsc['fcres'][uid])
+    >>> rsrc_api.create_or_replace(uid, init_gr=gr)
+
+Issuing a ``create_or_replace()`` on an existing UID will replace the existing
+property set with the provided one (PUT style).
+
+Create an LDP-NR::
+
+    >>> uid = '/test_ldpnr01'
+    >>> data = b'Hello. This is some dummy content.'
+    >>> rsrc_api.create_or_replace(
+    ...     uid, stream=BytesIO(data), mimetype='text/plain')
+    '_create_'
+
+Create under a known parent, providing a slug (POST style)::
+
+    >>> rsrc_api.create('/rsrc_from_stream', 'res1')
+
+
+Retrieve resources
+~~~~~~~~~~~~~~~~~~
+
+Retrieve a resource::
+
+    >>> rsrc = rsrc_api.get('/rsrc_from_stream')
+    >>> rsrc.uid
+    '/rsrc_from_stream'
+    >>> rsrc.uri
+    rdflib.term.URIRef('info:fcres/rsrc_from_stream')
+    >>> set(rsrc.metadata)
+    {(rdflib.term.URIRef('info:fcres/rsrc_from_stream'),
+      rdflib.term.URIRef('http://fedora.info/definitions/v4/repository#created'),
+      rdflib.term.Literal('2018-04-06T03:30:49.460274+00:00', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#dateTime'))),
+    [...]
+
+Retrieve non-RDF content::
+
+    >>> ldpnr = rsrc_api.get('/test_ldpnr01')
+    >>> ldpnr.content.read()
+    b'Hello. This is some dummy content.'
+
+See the :doc:`API docs <api>` for more details on resource methods.