Bump version to a11; refine documentation.

README.rst

@@ -11,10 +11,6 @@ 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.
 
-The full documentation is maintained in `Read The Docs
-<http://lakesuperior.readthedocs.io/>`__. Please refer to that for more info,
-including installation instructions.
-
 Guiding Principles
 ------------------
 
@@ -33,9 +29,7 @@ Its main goals are:
 Key features
 ------------
 
--  Drop-in replacement for Fedora4 (with some
-   :doc:`caveats <fcrepo4_deltas>`); currently being tested
-   with Hyrax 2
+-  Drop-in replacement for Fedora4
 -  Very stable persistence layer based on
    `LMDB <https://symas.com/lmdb/>`__ and filesystem. Fully
    ACID-compliant writes guarantee consistency of data.
@@ -47,6 +41,23 @@ Key features
    API.
 -  Fits in a pocket: you can carry 50M triples in an 8Gb memory stick.
 
+Installation & Documentation
+----------------------------
+
+With Docker::
+
+    git clone https://github.com/scossu/lakesuperior.git
+    cd lakesuperior
+    docker-compose up
+
+With pip (assuming you are familiar with it)::
+
+    pip install lakesuperior
+
+The full, current documentation is maintained in `Read The Docs
+<http://lakesuperior.readthedocs.io/>`__. Please refer to that for more info,
+including installation instructions.
+
 .. |build status| image:: http://img.shields.io/travis/scossu/lakesuperior/master.svg?style=flat
    :alt: Build Status
    :target: https://travis-ci.org/username/repo

docs/api.rst

@@ -1,23 +1,21 @@
-==================
 API Documentation
 ==================
 
 Main Interface
-==============
+--------------
 
 The LAKEsuperior API modules of most interest for a client are:
 
-- :mod:`Resource API <lakesuperior.api.resource>`
-- :mod:`Query API <lakesupeiror.api.query>`
-- :mod:`Admin API <lakesuperior.api.admin>`
+- :mod:`lakesuperior.api.resource`
+- :mod:`lakesupeiror.api.query`
+- :mod:`lakesuperior.api.admin`
 
-When manipulating resources the
-:mod:`Resource module <lakesuperior.model.ldpr>` is used.
+:mod:`lakesuperior.model.ldpr` is used to manipulate resources.
 
 The full API docs are listed below.
 
 Full API Documentation
-======================
+----------------------
 
 .. toctree::
    :caption: Modules

docs/cli.rst

@@ -4,30 +4,30 @@ LAKEsuperior Command Line Reference
 The LAKEsuperior command line tool is used for maintenance and
 administration purposes.
 
-The script is invoked from the main install directory. The tool is
-self-documented, so this is just a redundant overview:
+The script should be in your executable path if you install LAKEsuperior with
+``pip``. The tool is self-documented, so this is just a redundant overview::
 
-::
-
-    $ ./lsup_admin
+    $ lsup_admin
     Usage: lsup-admin [OPTIONS] COMMAND [ARGS]...
 
     Options:
       --help  Show this message and exit.
 
+    Commands:
       bootstrap     Bootstrap binary and graph stores.
       check_fixity  [STUB] Check fixity of a resource.
-      check_refint  [STUB] Check referential integrity.
+      check_refint  Check referential integrity.
       cleanup       [STUB] Clean up orphan database items.
-      copy          [STUB] Copy (backup) repository data.
-      dump          [STUB] Dump repository to disk.
-      load          [STUB] Load serialized repository data.
+      migrate       Migrate an LDP repository to LAKEsuperior.
       stats         Print repository statistics.
 
+*TODO: Add instructions to access from Docker.*
+
 All entries marked ``[STUB]`` are not yet implemented, however the
 ``lsup_admin <command> --help`` command will issue a description of what
-the command is meant to do. Please see the `TODO <TODO>`__ document for
-a rough road map.
+the command is meant to do. Check the
+`issues page <https://github.com/scossu/lakesuperior/issues>`__ for what's on
+the radar.
 
 All of the above commands are also available via, and based upon, the
 native Python API.

docs/contributing.rst

@@ -43,7 +43,13 @@ You can contribute by (from least to most involved):
 
 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
+Documentation is critical. If you implement new modules, class or methods, or
+modify them, please document them thoroughly and verify that the API docs are
+displaying and linking correctly.
+
+Likewise, please add mindful testing to new fatures or bug fixes.
+
+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

docs/messaging.rst

@@ -2,20 +2,21 @@ LAKEsuperior Messaging
 ======================
 
 LAKEsuperior implements a messaging system based on ActivityStreams, as
-indicated by the `Feodra API
+indicated by the `Fedora API
 specs <https://fedora.info/2017/06/30/spec/#notifications>`__. The
 metadata set provided is currently quite minimal but can be easily
-enriched by extending the `default formatter
-class <https://github.com/scossu/lakesuperior/blob/master/lakesuperior/messaging/messenger.py>`__.
+enriched by extending the
+:class:`~lakesuperior.messaging.messenger.Messenger` class.
 
 STOMP is the only supported protocol at the moment. More protocols may
 be made available at a later time.
 
 LAKEsuperior can send messages to any number of destinations: see
-`configuration <https://github.com/scossu/lakesuperior/blob/master/etc.defaults/application.yml#L79>`__.
-By default, CoilMQ is provided for testing purposes and listens to
-``localhost:61613``. The default route sends messages to
-``/topic/fcrepo``.
+:doc:`setup`.
+
+By default, `CoilMQ <https://github.com/hozn/coilmq>`__ is provided for testing
+purposes and listens to ``localhost:61613``. The default route sends messages
+to ``/topic/fcrepo``.
 
 A small command-line utility, also provided with the Python
 dependencies, allows to watch incoming messages. To monitor messages,
@@ -28,3 +29,29 @@ enter the following *after activating your virtualenv*:
 See the `stomp.py library reference
 page <https://github.com/jasonrbriggs/stomp.py/wiki/Command-Line-Access>`__
 for details.
+
+Disabing messaging
+------------------
+
+Messaging is enabled by default in LAKEsuperior. If you are not interested in
+interacting with an integration framework, you can save yourself some I/O and
+complexity and turn messaging off completely. In order to do that, set all
+entries in the ``routes`` section of ``application.yml`` to not active, e.g.::
+
+    [...]
+    messaging:
+        routes:
+        - handler: StompHandler
+          active: False # ← Disable the route
+              protocol: '11'
+              host: 127.0.0.1
+              port: 61613
+              username:
+              password:
+              destination: '/topic/fcrepo'
+              formatter: ASResourceFormatter
+
+A message queue does not need to be running in order for LAKEsuperior to
+operate, even if one or more routes are active. In that case, the application
+will throw a few ugly mssages and move on. *TODO: This should be handled more
+gracefully.*

docs/migration.rst

@@ -19,22 +19,17 @@ A repository can be migrated with a one-line command such as:
 
 ::
 
-    ./lsup-admin migrate http://source-repo.edu/rest /local/dest/folder
+    lsup-admin migrate http://source-repo.edu/rest /local/dest/folder
 
 For more options, enter
 
 ::
 
-    ./lsup-admin migrate --help
+    lsup-admin migrate --help
 
 The script will crawl through the resources and crawl through outbound
 links within them. In order to do this, resources are added as raw
-triples ( i.e. no consistency checks are made).
-
-**Note:** the consistency check tool has not yet been implemented at the
-moment but its release should follow shortly. This will ensure that all
-the links between resources are consistent in regard to referential
-integrity.
+triples, i.e. no consistency checks are made.
 
 This script will create a full dataset in the specified destination
 folder, complete with a default configuration that allows to start the
@@ -56,6 +51,19 @@ Two approaches to migration are possible:
    qualified URIs or paths relative to the repository root. (*TODO
    latter option needs testing*)
 
+Consistency check can (and should) be run after the migration::
+
+    lsup-admin check_refint
+
+This is critical to ensure that all resources in the repository are referencing
+to other repository resources that are actually existing.
+
+This feature has been added in alpha9.
+
+*TODO: The output of ``check_refint`` is somewhat crude. Improvements can be
+made to output integrity violations to a machine-readable log and integrate
+with the migration tool.*
+
 Backup And Restore
 ------------------
 

docs/setup.rst

@@ -72,7 +72,7 @@ Advanced Install
 ----------------
 
 A "developer mode" install is detailed in the
-:ref:`Development Setup<manual_install>` section.
+:ref:`Development Setup<dev_setup>` section.
 
 Configuration
 -------------

docs/usage.rst

@@ -1,8 +1,8 @@
 Sample Usage
-------------
+============
 
 LDP API
-=======
+-------
 
 The following are very basic examples of LDP interaction. For a more complete
 reference, please consult the `Fedora API guide

setup.py

@@ -27,7 +27,7 @@
 
 setup(
     name='lakesuperior',
-    version='1.0.0a10',
+    version='1.0.0a11',
 
     description='A Linked Data Platform repository sever.',
     long_description=long_description,