Many doc adjustments and additions. Good to publish.

docs/about.rst

@@ -0,0 +1,86 @@
+About LAKEsuperior
+==================
+
+LAKEsuperior is an alternative `Fedora
+Repository <http://fedorarepository.org>`__ implementation.
+
+Fedora is a mature repository software system historically adopted by
+major cultural heritage institutions. It exposes an
+`LDP <https://www.w3.org/TR/ldp-primer/>`__ endpoint to manage
+any type of binary files and their metadata in Linked Data format.
+
+Guiding Principles
+------------------
+
+LAKEsuperior aims at being an uncomplicated, efficient Fedora 4
+implementation.
+
+Its main goals are:
+
+-  **Reliability:** Based on solid technologies with stability in mind.
+-  **Efficiency:** Small memory and CPU footprint, high scalability.
+-  **Ease of management:** Tools to perform monitoring and maintenance
+   included.
+-  **Simplicity of design:** Straight-forward architecture, robustness
+   over features.
+
+Key features
+------------
+
+-  Drop-in replacement for Fedora4 (with some
+   :doc:`caveats <fcrepo4_deltas>`); currently being tested
+   with Hyrax 2
+-  Very stable persistence layer based on
+   `LMDB <https://symas.com/lmdb/>`__ and filesystem. Fully
+   ACID-compliant writes guarantee consistency of data.
+-  Term-based search (*planned*) and SPARQL Query API + UI
+-  No performance penalty for storing many resources under the same
+   container; no
+   `kudzu <https://www.nature.org/ourinitiatives/urgentissues/land-conservation/forests/kudzu.xml>`__
+   pairtree segmentation [#]_ 
+-  Extensible :doc:`provenance metadata <model>` tracking
+-  :doc:`Multi-modal access <architecture>`: HTTP
+   (REST), command line interface and native Python API.
+-  Fits in a pocket: you can carry 50M triples in an 8Gb memory stick.
+
+Implementation of the official `Fedora API
+specs <https://fedora.info/spec/>`__ (Fedora 5.x and beyond) is not
+foreseen in the short term, however it would be a natural evolution of
+this project if it gains support.
+
+Please make sure you read the :doc:`Delta
+document <fcrepo4_deltas>` for divergences with the
+official Fedora4 implementation.
+
+Target Audience
+---------------
+
+LAKEsuperior is for anybody who cares about preserving data in the long
+term.
+
+Less vaguely, LAKEsuperior is targeted at who needs to store large
+quantities of highly linked metadata and documents.
+
+Its Python/C environment and API make it particularly well suited for
+academic and scientific environments who would be able to embed it in a
+Python application as a library or extend it via plug-ins.
+
+LAKEsuperior is able to be exposed to the Web as a `Linked Data
+Platform <https://www.w3.org/TR/ldp-primer/>`__ server. It also acts as
+a SPARQL query (read-only) endpoint, however it is not meant to be used
+as a full-fledged triplestore at the moment.
+
+In its current status, LAKEsuperior is aimed at developers and hands-on
+managers who are interested in evaluating this project.
+
+Status and development
+----------------------
+
+LAKEsuperior is in **alpha** status. Please see the `project
+issues <https://github.com/scossu/lakesuperior/issues>`__ list for a
+rudimentary road map.
+
+--------------
+
+.. [#] However if your client splits pairtrees upstream, such as Hyrax does,
+   that obviously needs to change to get rid of the path segments.

docs/api.rst

@@ -1,32 +1,25 @@
+==================
 API Documentation
 ==================
 
-.. module:: lakesuperior
-
-Resource API
-~~~~~~~~~~~~
-
-.. automodule:: lakesuperior.api.resource
-   :members:
-
-Query API
-~~~~~~~~~
+Main Interface
+==============
 
-.. automodule:: lakesuperior.api.query
-   :members:
+The LAKEsuperior API modules of most interest for a client are:
 
-Admin API
-~~~~~~~~~
+- :mod:`Resource API <lakesuperior.api.resource>`
+- :mod:`Query API <lakesupeiror.api.query>`
+- :mod:`Admin API <lakesuperior.api.admin>`
 
-.. automodule:: lakesuperior.api.admin
-   :members:
+When manipulating resources the
+:mod:`Resource module <lakesuperior.model.ldpr>` is used.
 
+The full API docs are listed below.
 
-Full API docs
-~~~~~~~~~~~~~
+Full API Documentation
+======================
 
 .. toctree::
-   :maxdepth: 3
-   :glob:
+   :caption: Modules
 
-   apidoc/*
+   apidoc/modules

docs/apidoc/lakesuperior.api.rst

@@ -0,0 +1,38 @@
+lakesuperior\.api package
+=========================
+
+Submodules
+----------
+
+lakesuperior\.api\.admin module
+-------------------------------
+
+.. automodule:: lakesuperior.api.admin
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lakesuperior\.api\.query module
+-------------------------------
+
+.. automodule:: lakesuperior.api.query
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lakesuperior\.api\.resource module
+----------------------------------
+
+.. automodule:: lakesuperior.api.resource
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: lakesuperior.api
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/lakesuperior.endpoints.rst

@@ -0,0 +1,46 @@
+lakesuperior\.endpoints package
+===============================
+
+Submodules
+----------
+
+lakesuperior\.endpoints\.admin module
+-------------------------------------
+
+.. automodule:: lakesuperior.endpoints.admin
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lakesuperior\.endpoints\.ldp module
+-----------------------------------
+
+.. automodule:: lakesuperior.endpoints.ldp
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lakesuperior\.endpoints\.main module
+------------------------------------
+
+.. automodule:: lakesuperior.endpoints.main
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lakesuperior\.endpoints\.query module
+-------------------------------------
+
+.. automodule:: lakesuperior.endpoints.query
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: lakesuperior.endpoints
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/lakesuperior.messaging.rst

@@ -0,0 +1,38 @@
+lakesuperior\.messaging package
+===============================
+
+Submodules
+----------
+
+lakesuperior\.messaging\.formatters module
+------------------------------------------
+
+.. automodule:: lakesuperior.messaging.formatters
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lakesuperior\.messaging\.handlers module
+----------------------------------------
+
+.. automodule:: lakesuperior.messaging.handlers
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lakesuperior\.messaging\.messenger module
+-----------------------------------------
+
+.. automodule:: lakesuperior.messaging.messenger
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: lakesuperior.messaging
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/lakesuperior.rst

@@ -6,7 +6,11 @@ Subpackages
 
 .. toctree::
 
+    lakesuperior.api
+    lakesuperior.endpoints
+    lakesuperior.messaging
     lakesuperior.model
+    lakesuperior.store
 
 Submodules
 ----------

docs/apidoc/lakesuperior.store.ldp_nr.rst

@@ -0,0 +1,30 @@
+lakesuperior\.store\.ldp\_nr package
+====================================
+
+Submodules
+----------
+
+lakesuperior\.store\.ldp\_nr\.base\_non\_rdf\_layout module
+-----------------------------------------------------------
+
+.. automodule:: lakesuperior.store.ldp_nr.base_non_rdf_layout
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lakesuperior\.store\.ldp\_nr\.default\_layout module
+----------------------------------------------------
+
+.. automodule:: lakesuperior.store.ldp_nr.default_layout
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: lakesuperior.store.ldp_nr
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/lakesuperior.store.ldp_rs.rst

@@ -0,0 +1,30 @@
+lakesuperior\.store\.ldp\_rs package
+====================================
+
+Submodules
+----------
+
+lakesuperior\.store\.ldp\_rs\.lmdb\_store module
+------------------------------------------------
+
+.. automodule:: lakesuperior.store.ldp_rs.lmdb_store
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lakesuperior\.store\.ldp\_rs\.rsrc\_centric\_layout module
+----------------------------------------------------------
+
+.. automodule:: lakesuperior.store.ldp_rs.rsrc_centric_layout
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: lakesuperior.store.ldp_rs
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/lakesuperior.store.rst

@@ -0,0 +1,18 @@
+lakesuperior\.store package
+===========================
+
+Subpackages
+-----------
+
+.. toctree::
+
+    lakesuperior.store.ldp_nr
+    lakesuperior.store.ldp_rs
+
+Module contents
+---------------
+
+.. automodule:: lakesuperior.store
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/contributing.rst

@@ -0,0 +1,40 @@
+Contributing to LAKEsuperior
+============================
+
+LAKEsuperior has been so far a single person’s off-hours project (with much
+very valuable input from several sides). In order to turn into anything close
+to a Beta release and eventually to a production-ready implementation, it
+needs some community love.
+
+Contributions are welcome in all forms, including ideas, issue reports,
+or even just spinning up the software and providing some feedback.
+LAKEsuperior is meant to live as a community project.
+
+Development Setup
+-----------------
+
+To set up the software for developing code, documentation, or tests, follow the
+:ref:`manual installation <manual_install>` instructions.
+The additional packages indicated as optional need to be installed.
+
+Contribution Guidelines
+-----------------------
+
+You can contribute by (from least to most involved):
+
+- Installing the repository and reporting any issues
+- Testing on other platforms (OS X, Windows, other Linux distros)
+- Loading some real-world data set and sharing interesting results
+- Amending incorrect documentation or adding missing one
+- Adding test coverage (**HOT**)
+- Browsing the list of open issues and picking a ticket that you may find
+  interesting and within your reach
+- Suggesting new functionality or improvements and/or implementing them
+
+Please open a ticket and discuss the issue you are raising before opening a PR.
+
+Development is done on the development branch. If you have any suggested
+addition to the code, please fork the repo, create a new branch for your topic
+and open a pull request against development. In case you find a critical bug,
+a hotfix can be proposed against master if agreed in the related issue
+discussion.

docs/fcrepo4_deltas.rst

@@ -144,6 +144,11 @@ This should not pose a problem if a client does not have ``rest``
 hard-coded in its code, but in any event, the ``/rest`` endpoint is
 provided for backwards compatibility.
 
+Future implementations of the Fedora API specs may employ a "versioned"
+endpoint scheme that allows multiple Fedora API versions to be available to the
+client, e.g. ``/ldp/fc4`` for the current LDP API version, ``/ldp/fc5`` for
+Fedora version 5.x, etc.
+
 Automatic LDP class assignment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -154,7 +159,7 @@ from the provided properties: if the ``ldp:hasMemberRelation`` and
 Direct Container. If in addition to these the
 ``ldp:insertedContentRelation`` property is present, the resource is an
 Indirect Container. If any of the first two are missing, the resource is
-a Container (@TODO discuss: shall it be a Basic Container?)
+a Container.
 
 Clients are encouraged to omit LDP types in PUT, POST and PATCH
 requests.

docs/help.rst

@@ -0,0 +1,9 @@
+Getting Help
+============
+
+Discussion is on the `lakesuperior
+<https://groups.google.com/forum/#!forum/lakesuperior>`__ Google group.
+
+You can report bugs or feature requests on the `Github issues page
+<https://github.com/scossu/lakesuperior/issues>`__. Please start a conversation
+in the Google group before filing an issue, especially for feature requests.

docs/index.rst

@@ -11,123 +11,42 @@ major cultural heritage institutions. It exposes an
 `LDP <https://www.w3.org/TR/ldp-primer/>`__ endpoint to manage
 any type of binary files and their metadata in Linked Data format.
 
-Guiding Principles
-------------------
-
-LAKEsuperior aims at being an uncomplicated, efficient Fedora 4
-implementation.
-
-Its main goals are:
-
--  **Reliability:** Based on solid technologies with stability in mind.
--  **Efficiency:** Small memory and CPU footprint, high scalability.
--  **Ease of management:** Tools to perform monitoring and maintenance
-   included.
--  **Simplicity of design:** Straight-forward architecture, robustness
-   over features.
-
-Key features
-------------
-
--  Drop-in replacement for Fedora4 (with some
-   :doc:`caveats <fcrepo4_deltas>`); currently being tested
-   with Hyrax 2
--  Very stable persistence layer based on
-   `LMDB <https://symas.com/lmdb/>`__ and filesystem. Fully
-   ACID-compliant writes guarantee consistency of data.
--  Term-based search (*planned*) and SPARQL Query API + UI
--  No performance penalty for storing many resources under the same
-   container; no
-   `kudzu <https://www.nature.org/ourinitiatives/urgentissues/land-conservation/forests/kudzu.xml>`__
-   pairtree segmentation \ `1 <#f1>`__\ 
--  Extensible :doc:`provenance metadata <model>` tracking
--  :doc:`Multi-modal access <architecture>`: HTTP
-   (REST), command line interface and native Python API.
--  Fits in a pocket: you can carry 50M triples in an 8Gb memory stick.
-
-Implementation of the official `Fedora API
-specs <https://fedora.info/spec/>`__ (Fedora 5.x and beyond) is not
-foreseen in the short term, however it would be a natural evolution of
-this project if it gains support.
-
-Please make sure you read the :doc:`Delta
-document <fcrepo4_deltas>` for divergences with the
-official Fedora4 implementation.
-
-Target Audience
----------------
-
-LAKEsuperior is for anybody who cares about preserving data in the long
-term.
-
-Less vaguely, LAKEsuperior is targeted at who needs to store large
-quantities of highly linked metadata and documents.
-
-Its Python/C environment and API make it particularly well suited for
-academic and scientific environments who would be able to embed it in a
-Python application as a library or extend it via plug-ins.
-
-LAKEsuperior is able to be exposed to the Web as a `Linked Data
-Platform <https://www.w3.org/TR/ldp-primer/>`__ server. It also acts as
-a SPARQL query (read-only) endpoint, however it is not meant to be used
-as a full-fledged triplestore at the moment.
-
-In its current status, LAKEsuperior is aimed at developers and hands-on
-managers who are interested in evaluating this project.
-
-Status and development
-----------------------
-
-LAKEsuperior is in **alpha** status. Please see the `project
-issues <https://github.com/scossu/lakesuperior/issues>`__ list for a
-rudimentary road map.
-
-Contributing
-------------
-
-This has been so far a single person’s off-hours project (with much
-input from several sides). In order to turn into anything close to a
-Beta release and eventually to a production-ready implementation, it
-needs some community love.
-
-Contributions are welcome in all forms, including ideas, issue reports,
-or even just spinning up the software and providing some feedback.
-LAKEsuperior is meant to live as a community project.
-
---------------
-
-1 However if your client splits pairtrees upstream, such as Hyrax does,
-that obviously needs to change to get rid of the path segments.
-`↩ <#a1>`__
-
 .. |build status| image:: http://img.shields.io/travis/scossu/lakesuperior/master.svg?style=flat
    :target: https://travis-ci.org/username/repo
 
 Indices and tables
 ------------------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
 .. toctree::
    :maxdepth: 2
-   :caption: Contents
+   :caption: Getting Started
 
+    About LAKEsuperior <about>
     Installation and Configuration <setup>
-    Architecture Overview <architecture>
+    Sample Usage <usage>
+    Getting Help <help>
+
+.. toctree::
+   :maxdepth: 3
+   :caption: User Reference
+
     Divergences from Fedora 4 <fcrepo4_deltas>
     Messaging <messaging>
     Migration Guide <migration>
     Command Line Reference <cli>
-    Performance Benchmarks <performance>
+    Contributing <contributing>
 
 .. toctree::
-   :maxdepth: 1
-   :caption: In-depth tech & design
+   :maxdepth: 2
+   :caption: Technical Documents
 
-    Contributing <contributing>
-    API documentation <api>
-    Indexing Strategy <indexing_strategy>
-    Storage Implementation <storage>
+    API Documentation <api>
+    Architecture <architecture>
+    Performance Benchmarks <performance>
     Content Model <model>
+    Storage Implementation <storage>
+    Indexing Strategy <indexing_strategy>
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/model.rst

@@ -39,8 +39,8 @@ recording of provenance metadata while providing reasonable performance.
 
 Store layout modules could be replaceable (work needs to be done to
 develop an interface to allow that). The default (and only at the
-moment) layout shipped with LAKEsuperior is the `resource-centric
-layout <../../lakesuperior/store/ldp_rs/rsrc_centric_layout>`__. This
+moment) layout shipped with LAKEsuperior is the :mod:`resource-centric
+layout <lakesuperior.store.ldp_rs.rsrc_centric_layout>`. This
 layout implements a so-called `graph-per-aspect
 pattern <http://patterns.dataincubator.org/book/graph-per-aspect.html>`__
 which stores different sets of statements about a resource in separate
@@ -55,9 +55,8 @@ The named graphs used for each resource are:
    reserved for containment triples. The reason for this separation is
    purely convenience, since it makes it easy to retrieve all the
    properties of a large container without its child references.
--  One (and, possibly, in the future, more user-defined) named graph for
-   user-provided data
-   (``info:fcsystem/graph/userdata/_main<resource UID>``).
+-  One (and, possibly, in the future, more user\-defined) named graph for
+   user-provided data (``info:fcsystem/graph/userdata/_main<resource UID>``).
 
 Each of these graphs can be annotated with provenance metadata. The
 layout decides which triples go in which graph based on the predicate or

docs/performance.rst

@@ -18,7 +18,9 @@ Hardware
 ‘Ole Workhorse’ server
 ^^^^^^^^^^^^^^^^^^^^^^
 
-8x Intel(R) Xeon(R) CPU X5550 @ 2.67GHz 16Gb RAM Magnetic drive, XXX RPM
+-  8x Intel(R) Xeon(R) CPU X5550 @ 2.67GHz
+-  16Gb RAM
+-  Magnetic drive, XXX RPM
 
 Software
 ~~~~~~~~

docs/setup.rst

@@ -26,6 +26,8 @@ self-container Docker volume, meaning your data will persist between
 runs. If you want to clear the decks, simply run
 ``docker-compose down -v``.
 
+.. _manual_install:
+
 Manual Install (a bit less quick, a bit more power)
 ---------------------------------------------------
 
@@ -36,28 +38,37 @@ modifications. Feedback is welcome.
 Dependencies
 ~~~~~~~~~~~~
 
-1. Python 3.5 or greater.
-2. A message broker supporting the STOMP protocol. For testing and
+#. Python 3.5 or greater.
+#. A message broker supporting the STOMP protocol. For testing and
    evaluation purposes, `CoilMQ <https://github.com/hozn/coilmq>`__ is
    included with the dependencies and should be automatically installed.
 
 Installation steps
 ~~~~~~~~~~~~~~~~~~
 
-1. Create a virtualenv in a project folder:
+#. Create a virtualenv in a project folder:
    ``virtualenv -p <python 3.5+ exec path> <virtualenv folder>``
-2. Activate the virtualenv: ``source <path_to_virtualenv>/bin/activate``
-3. Clone this repo:
+#. Activate the virtualenv: ``source <path_to_virtualenv>/bin/activate``
+#. Clone this repo:
    ``git clone https://github.com/scossu/lakesuperior.git``
-4. ``cd`` into repo folder
-5. Install dependencies: ``pip install -r requirements.txt``
-6. Start your STOMP broker, e.g.: ``coilmq &``. If you have another
-   queue manager listening to port 61613 you can either configure a
-   different port on the application configuration, or use the existing
-   message queue.
-7. Run ``./lsup-admin bootstrap`` to initialize the binary and graph
-   stores
-8. Run ``./fcrepo``.
+#. ``cd`` into repo folder
+#. Install dependencies: ``pip install -r requirements.txt``
+
+   - (Optional) For a development server, install additional dependencies:
+     ``pip install -r requirements_dev.txt``. These include some heavyweight
+     packages needed for development and testing but not for regular operation.
+
+#. Start your STOMP broker, e.g.: ``coilmq &``.
+
+   - If you have another
+     queue manager listening to port 61613 you can either configure a
+     different port on the application configuration, or use the existing
+     message queue.
+
+#. Make sure that the ``lsup-admin`` and ``fcrepo`` files are executable.
+#. Run ``./lsup-admin bootstrap`` to initialize the binary and graph
+   stores.
+#. Run ``./fcrepo``.
 
 Configuration
 -------------

docs/usage.rst

@@ -0,0 +1,117 @@
+Sample Usage
+------------
+
+LDP API
+=======
+
+The following are very basic examples of LDP interaction. For a more complete
+reference, please consult the `Fedora API guide
+<https://wiki.duraspace.org/display/FEDORA4x/RESTful+HTTP+API+-+Containers>`__.
+
+**Note**: At the moment the LDP API only support the Turtle format for
+serializing and deserializing RDF.
+
+Create an empty LDP container (LDPC)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl -X POST http://localhost:8000/ldp
+
+
+Create a resource with RDF payload
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl -X POST -H'Content-Type:text/turtle' --data-binary '<> <urn:ns:p1> <urn:ns:o1> .' http://localhost:8000/ldp
+
+
+Create a resource at a specific location
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl -X PUT http://localhost:8000/ldp/res1
+
+
+Create a binary resource
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl -X PUT -H'Content-Type:image/png' --data-binary '@/home/me/image.png' http://localhost:8000/ldp/bin1
+
+
+Retrieve an RDF resource (LDP-RS)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl http://localhost:8000/ldp/res1
+
+Retrieve a non-RDF source (LDP-NR)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl http://localhost:8000/ldp/bin1
+
+Or::
+
+    curl http://localhost:8000/ldp/bin1/fcr:content
+
+Or::
+
+    curl -H'Accept:image/png' http://localhost:8000/ldp/bin1
+
+Retrieve RDF metadata of a LDP-NR
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl http://localhost:8000/ldp/bin1/fcr:metadata
+
+Or::
+
+    curl -H'Accept:text/turtle' http://localhost:8000/ldp/bin1
+
+
+Soft-delete a resource
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl -X DELETE http://localhost:8000/ldp/bin1
+
+
+Restore ("resurrect") a resource
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl -X POST http://localhost:8000/ldp/bin1/fcr:tombstone
+
+
+Permanently delete ("forget") a soft-deleted resource
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Note**: the following command cannot be issued after the previous one. It has
+to be issued on a soft-deleted, non-resurrected resource.
+
+::
+
+    curl -X DELETE http://localhost:8000/ldp/bin1/fcr:tombstone
+
+Immediately forget a resource
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    curl -X DELETE -H'Prefer:no-tombstone' http://localhost:8000/ldp/res1
+
+
+Python API
+----------
+
+**TODO**

lakesuperior/endpoints/ldp.py

@@ -112,16 +112,17 @@ def log_request_end(rsp):
 @ldp.route('/<path:uid>/fcr:content', defaults={'out_fmt' : 'non_rdf'},
         methods=['GET'])
 def get_resource(uid, out_fmt=None):
-    """
+    r"""
     https://www.w3.org/TR/ldp/#ldpr-HTTP_GET
 
     Retrieve RDF or binary content.
 
     :param str uid: UID of resource to retrieve. The repository root has
-    an empty string for UID.
+        an empty string for UID.
     :param str out_fmt: Force output to RDF or non-RDF if the resource is
-    a LDP-NR. This is not available in the API but is used e.g. by the
-    `*/fcr:metadata` and `*/fcr:content` endpoints. The default is False.
+        a LDP-NR. This is not available in the API but is used e.g. by the
+        ``\*/fcr:metadata`` and ``\*/fcr:content`` endpoints. The default is
+        False.
     """
     logger.info('UID: {}'.format(uid))
     out_headers = std_headers
@@ -171,6 +172,8 @@ def get_resource(uid, out_fmt=None):
 def get_version_info(uid):
     """
     Get version info (`fcr:versions`).
+
+    :param str uid: UID of resource to retrieve versions for.
     """
     try:
         gr = rsrc_api.get_version_info(uid)
@@ -353,7 +356,7 @@ def delete_resource(uid):
     one more version snapshot of the resource prior to being deleted.
 
     In order to completely wipe out all traces of a resource, the tombstone
-    must be deleted as well, or the `Prefer:no-tombstone` header can be used.
+    must be deleted as well, or the ``Prefer:no-tombstone`` header can be used.
     The latter will forget (completely delete) the resource immediately.
     """
     headers = std_headers
@@ -595,7 +598,7 @@ def _headers_from_metadata(rsrc):
     Create a dict of headers from a metadata graph.
 
     :param lakesuperior.model.ldpr.Ldpr rsrc: Resource to extract metadata
-    from.
+        from.
     """
     out_headers = defaultdict(list)
 

lakesuperior/model/ldpr.py

@@ -134,7 +134,7 @@ class Ldpr(metaclass=ABCMeta):
         The RDFLib resource representing this LDPR. This is a live
         representation of the stored data if present.
 
-        :rtype: rdflib.resource.Resource
+        :rtype: rdflib.Resource
         """
         if not hasattr(self, '_rsrc'):
             self._rsrc = rdfly.ds.resource(self.uri)
@@ -150,7 +150,7 @@ class Ldpr(metaclass=ABCMeta):
         If the resource is not stored (yet), a `ResourceNotExistsError` is
         raised.
 
-        @return rdflib.resource.Resource
+        :rtype: rdflib.Resource
         """
         if not hasattr(self, '_imr'):
             if hasattr(self, '_imr_options'):

lakesuperior/store/ldp_nr/default_layout.py

@@ -25,7 +25,7 @@ class DefaultLayout(BaseNonRdfLayout):
         configuration parameters.
 
         :param str uuid: The resource UUID. This corresponds to the content
-        checksum.
+            checksum.
         """
         logger.debug('Generating path from uuid: {}'.format(uuid))
         term = len(uuid) if bc == 0 else min(bc * bl, len(uuid))
@@ -59,7 +59,7 @@ class DefaultLayout(BaseNonRdfLayout):
 
 
     def persist(self, stream, bufsize=8192):
-        """
+        r"""
         Store the stream in the file system.
 
         This method handles the file in chunks. for each chunk it writes to a
@@ -67,8 +67,8 @@ class DefaultLayout(BaseNonRdfLayout):
         to disk and hashed, the temp file is moved to its final location which
         is determined by the hash value.
 
-        :param IOstream stream:: file-like object to persist.
-        :param int bufsize: Chunk size. 2**12 to 2**15 is a good range.
+        :param IOstream stream: file-like object to persist.
+        :param int bufsize: Chunk size. 2\*\*12 to 2\*\*15 is a good range.
         """
         tmp_file = '{}/tmp/{}'.format(self.root, uuid4())
         try:

lakesuperior/store/ldp_rs/lmdb_store.py

@@ -36,7 +36,7 @@ class TxnManager(ContextDecorator):
     """
     Handle ACID transactions with an LmdbStore.
 
-    Wrap this within a `with` statement:
+    Wrap this within a ``with`` statement:
 
     >>> with TxnManager(store, True):
     ...     # Do something with the database
@@ -50,7 +50,7 @@ class TxnManager(ContextDecorator):
 
         :param LmdbStore store: The store to open a transaction on.
         :param bool write: Whether the transaction is read-write. Default is
-        False (read-only transaction).
+            ``False`` (read-only transaction).
         """
         self.store = store
         self.write = write
@@ -79,12 +79,13 @@ class LexicalSequence:
         Create a new lexical sequence.
 
         :param bytes start: Starting byte value. Bytes below this value are
-        never found in this sequence. This is useful to allot special bytes
-        to be used e.g. as separators.
+            never found in this sequence. This is useful to allot special bytes
+            to be used e.g. as separators.
         :param int max_len: Maximum number of bytes that a byte string can
-        contain. This should be chosen carefully since the number of all
-        possible key combinations is determined by this value and the `start`
-        value. The default args provide 255**5 (~1 Tn) unique combinations.
+            contain. This should be chosen carefully since the number of all
+            possible key combinations is determined by this value and the
+            ``start`` value. The default args provide 255**5 (~1 Tn) unique
+            combinations.
         """
         self.start = start
         self.length = max_len
@@ -152,26 +153,26 @@ class LmdbStore(Store):
 
     There are 4 main data sets (preservation worthy data):
 
-    - t:st (term key: serialized term; 1:1)
-    - spo:c (joined S, P, O keys: context key; dupsort, dupfixed)
-    - c: (context keys only, values are the empty bytestring; 1:1)
-    - pfx:ns (prefix: pickled namespace; 1:1)
+    - `t:st` (term key: serialized term; 1:1)
+    - `spo:c` (joined S, P, O keys: context key; dupsort, dupfixed)
+    - `c:` (context keys only, values are the empty bytestring; 1:1)
+    - `pfx:ns` (prefix: pickled namespace; 1:1)
 
     And 6 indices to optimize lookup for all possible bound/unbound term
     combination in a triple:
 
-    - th:t (term hash: term key; 1:1)
-    - s:po (S key: joined P, O keys; dupsort, dupfixed)
-    - p:so (P key: joined S, O keys; dupsort, dupfixed)
-    - o:sp (O key: joined S, P keys; dupsort, dupfixed)
-    - c:spo (context → triple association; dupsort, dupfixed)
-    - ns:pfx (pickled namespace: prefix; 1:1)
-
-    The default graph is defined in `RDFLIB_DEFAULT_GRAPH_URI`. Adding triples
-    without context will add to this graph. Looking up triples without context
-    (also in a SPARQL query) will look in the  union graph instead of in the
-    default graph. Also, removing triples without specifying a context will
-    remove triples from all contexts.
+    - `th:t` (term hash: term key; 1:1)
+    - `s:po` (S key: joined P, O keys; dupsort, dupfixed)
+    - `p:so` (P key: joined S, O keys; dupsort, dupfixed)
+    - `o:sp` (O key: joined S, P keys; dupsort, dupfixed)
+    - `c:spo` (context → triple association; dupsort, dupfixed)
+    - `ns:pfx` (pickled namespace: prefix; 1:1)
+
+    The default graph is defined in :data:`RDFLIB_DEFAULT_GRAPH_URI`. Adding
+    triples without context will add to this graph. Looking up triples without
+    context (also in a SPARQL query) will look in the  union graph instead of
+    in the default graph. Also, removing triples without specifying a context
+    will remove triples from all contexts.
     """
 
     context_aware = True
@@ -453,7 +454,7 @@ class LmdbStore(Store):
 
         :param tuple(rdflib.Identifier) triple: Tuple of three identifiers.
         :param context: Context identifier. ``None`` inserts in the default
-        graph.
+            graph.
         :type context: rdflib.Identifier or None
         :param bool quoted: Not used.
         """
@@ -557,11 +558,15 @@ class LmdbStore(Store):
         Generator over matching triples.
 
         :param tuple triple_pattern: 3 RDFLib terms
-        :param rdflib.Graph | None context: Context graph, if available.
+        :param context: Context graph, if available.
+        :type context: rdflib.Graph or None
 
+        :rtype: Iterator
         :return: Generator over triples and contexts in which each result has
-        the following format:
-        > (s, p, o), generator(contexts)
+            the following format::
+
+            (s, p, o), generator(contexts)
+
         Where the contexts generator lists all context that the triple appears
         in.
         """

lakesuperior/store/ldp_rs/rsrc_centric_layout.py

@@ -193,7 +193,7 @@ class RsrcCentricLayout:
 
         :param rdflib.term.URIRef s: URI of the subject.
         :param rdflib.term.URIRef ctx: URI of the optional context. If None,
-        all named graphs are queried.
+            all named graphs are queried.
 
         :rtype: rdflib.Graph
         """
@@ -348,7 +348,7 @@ class RsrcCentricLayout:
 
         :param rdflib.URIRef subj_uri: Subject URI.
         :param boolean full_triple: Whether to return the full triples found
-        or only the subjects. By default, full triples are returned.
+            or only the subjects. By default, full triples are returned.
 
         :rtype: Iterator(tuple(rdflib.term.Identifier) or rdflib.URIRef)
         :return: Inbound triples or subjects.
@@ -368,10 +368,9 @@ class RsrcCentricLayout:
         """
         Get descendants (recursive children) of a resource.
 
-        :param string uid: Resource UID.
-        result set.
+        :param str uid: Resource UID.
 
-        :rtype: iterator(rdflib.URIRef)
+        :rtype: Iterator(rdflib.URIRef)
         :return: Subjects of descendant resources.
         """
         ds = self.ds
@@ -399,7 +398,7 @@ class RsrcCentricLayout:
         The statement(s) is/are executed on the user-provided graph only
         to ensure that the scope is limited to the resource.
 
-        :param string uid: UID of the resource to be patched.
+        :param str uid: UID of the resource to be patched.
         :param dict qry: Parsed and translated query, or query string.
         """
         # Add meta graph for user-defined triples. This may not be used but