New and updated documentation (incomplete).

README.md

@@ -54,8 +54,8 @@ divergences with the official Fedora4 implementation.
 1. The [LMDB](https://symas.com/lmdb/) database library. It should be included
 in most Linux distributions' standard package repositories.
 1. A message broker supporting the STOMP protocol. For testing and evaluation
-purposes, Coilmq is included in the dependencies and should be automatically
-installed.
+purposes, [Coilmq](https://github.com/hozn/coilmq) is included with the
+dependencies and should be automatically installed.
 
 ### Installation steps
 
@@ -71,10 +71,10 @@ installed.
    `export FCREPO_CONFIG_DIR=<your config dir location>` (alternatively you can
    add this line to your virtualenv `activate` script)
 1. Configure the application
-1. Start your STOMP broker
+1. Start your STOMP broker, e.g.: `coilmq &`
 1. Run `util/bootstrap.py` to initialize the binary and graph stores
-1. Run `./fcrepo` for a multi-threaded server or `flask run` for a
-   single-threaded development server
+1. Run `./fcrepo` for a single-threaded server (Bjoern) or `./fcrepo-mt` for a
+   multi-threaded development server (GUnicorn).
 
 ### Production deployment
 
@@ -87,9 +87,13 @@ for a rudimentary road map and status.
 
 ## Technical documentation
 
-[Storage Implementation](doc/notes/torage.md)
+[Architecture Overview](doc/notes/architecture.md)
 
-[Performance benchmarks](doc/notes/performance.md)
+[Content Model](doc/notes/model.md)
+
+[Storage Implementation](doc/notes/storage.md)
+
+[Performance Benchmarks](doc/notes/performance.md)
 
 [TODO list](doc/notes/TODO)
 

doc/notes/TODO

@@ -91,8 +91,9 @@
   - [D] Admin
   - [D] Query
 - [D] Align logger variable
+- [D] UIDs start with a slash
 - [ ] CLI prototype
-- [ ] Update documentation
+- [W] Update documentation
 
 # Alpha 8
 

doc/notes/architecture.md

@@ -5,15 +5,41 @@
 LAKEsuperior is written in Python. It is not excluded that parts of the code
 may be rewritten in [Cython](http://cython.readthedocs.io/) for performance.
 
-![LAKEsuperior Architecture](../assets/lakesuperior_arch.png)
 
-LAKEsuperior is accessible in multiple ways:
+## Multi-Modal Access
+
+LAKEsuperior services and data are accessible in multiple ways:
 
-- Via HTTP. This is the canonical way to interact with LDP resources.
+- Via HTTP. This is the canonical way to interact with LDP resources and
+  conforms quite closely to the Fedora specs (currently v4).
 - Via command line. This method includes long-running admin tasks which are not
   available via HTTP.
 - Via a Python API. This method allows to use Python scripts to access the same
   methods available to the two methods above in a programmatic way. It is
-  possible to write Python plugins or even completely embed LAKEsuperior in a
-  Python application.
+  possible to write Python plugins or even to embed LAKEsuperior in a
+  Python application, even without running a web server.
+
+
+## Architecture Overview
+
+![LAKEsuperior Architecture](../assets/lakesuperior_arch.png)
+
+The LAKEsuperior REST API provides access to the underlying Python API. All
+REST and CLI operations can be replicated by a Python program accessing this
+API.
+
+The main advantage of the Python API is that it makes it very easy to maipulate
+graph and binary data without the need to serialize or deserialize native data
+structures. This matters when handling large ETL jobs for example.
+
+The Python API is divided in three main areas:
+
+- [Resource API](../../lakesuperior/api/resource.py). This API is in charge of
+  all the resource CRUD operations and implements the majority of the Fedora
+  specs.
+- [Admin API](../../lakesuperior/api/admin.py). This exposes utility methods,
+  mostly long-running maintenance jobs.
+- [Query API](../../lakesuperior/api/query.py). This provides several
+  facilities for querying repository data.
+
 

doc/notes/performance.md

@@ -19,7 +19,7 @@
 
 ### Benchmark script
 
-[Generator script](../../tests/10K_children.py)
+[Generator script](../../util/benchmark.py)
 
 The script was run with default values: 10,000 children under the same parent,
 PUT requests.

lakesuperior/api/resource.py

@@ -21,6 +21,42 @@ from lakesuperior.store.ldp_rs.lmdb_store import TxnManager
 logger = logging.getLogger(__name__)
 app_globals = env.app_globals
 
+__doc__ = '''
+Primary API for resource manipulation.
+
+Quickstart:
+
+>>> # First import default configuration and globals—only done once.
+>>> import lakesuperior.default_env
+>>> from lakesuperior.api import resource
+>>> # Get root resource.
+>>> rsrc = resource.get('/')
+>>> # Dump graph.
+>>> set(rsrc.imr())
+{(rdflib.term.URIRef('info:fcres/'),
+  rdflib.term.URIRef('http://purl.org/dc/terms/title'),
+  rdflib.term.Literal('Repository Root')),
+ (rdflib.term.URIRef('info:fcres/'),
+  rdflib.term.URIRef('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+  rdflib.term.URIRef('http://fedora.info/definitions/v4/repository#Container')),
+ (rdflib.term.URIRef('info:fcres/'),
+  rdflib.term.URIRef('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+  rdflib.term.URIRef('http://fedora.info/definitions/v4/repository#RepositoryRoot')),
+ (rdflib.term.URIRef('info:fcres/'),
+  rdflib.term.URIRef('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+  rdflib.term.URIRef('http://fedora.info/definitions/v4/repository#Resource')),
+ (rdflib.term.URIRef('info:fcres/'),
+  rdflib.term.URIRef('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+  rdflib.term.URIRef('http://www.w3.org/ns/ldp#BasicContainer')),
+ (rdflib.term.URIRef('info:fcres/'),
+  rdflib.term.URIRef('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+  rdflib.term.URIRef('http://www.w3.org/ns/ldp#Container')),
+ (rdflib.term.URIRef('info:fcres/'),
+  rdflib.term.URIRef('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+  rdflib.term.URIRef('http://www.w3.org/ns/ldp#RDFSource'))}
+
+'''
+
 def transaction(write=False):
     '''
     Handle atomic operations in a store.

lakesuperior/model/ldpr.py

@@ -758,7 +758,7 @@ class Ldpr(metaclass=ABCMeta):
                 parent_rsrc = LdpFactory.new_container(cnd_parent_uid)
                 # This will trigger this method again and recurse until an
                 # existing container or the root node is reached.
-                parent_rsrc.put()
+                parent_rsrc.create_or_replace_rsrc()
                 parent_uid = parent_rsrc.uid
         else:
             parent_uid = ROOT_UID