docs: INSTALL.rst and modules

Signed-off-by: Dinos Kousidis <[email protected]>

INSTALL.rst

@@ -225,36 +225,110 @@ Before installing B2Share you will need the following software:
     $ brew install python --framework --universal
     $ pip install virtualenv virtualenvwrapper
 
-- ``docker`` and ``docker-compose``
+and a working installation of the following services:
 
-On macOS we recommend using Docker for Mac.
+- ``Elasticsearch 2.4``
+- ``Redis 2.10.5``
+- ``RabbitMQ 3.6``
+- ``Celery 4.1``
+- ``PostgreSQL 9.6`` and ``psycopg2``
 
-If the conditions are satisfied, open one terminal window and download in a
-temporary folder the ``devenv/docker-compose`` and ``devenv/run_demo.sh``
-files:
+Another option, which requires a bit more RAM, is to use a docker-compose.yml file
+to manage the starting and stopping of the services,
+and just have a bare metal installation of B2Share for development.
+
+Now to install B2Share, first create a new virtualenv with:
+
+.. code-block:: console
+
+    $ virtualenv -p python3 b2share
+
+and clone the B2Share repository from github:
 
 .. code-block:: console
+    
+    $ git clone https://github.com/eudat-b2share/b2share.git
 
-    $ mdir develop-b2share
-    $ cd develop-b2share
-    $ curl -O https://raw.githubusercontent.com/EUDAT-B2SHARE/b2share/master/devenv/docker-compose.yml
-    $ curl -O https://raw.githubusercontent.com/EUDAT-B2SHARE/b2share/master/devenv/run_demo.sh
+Now we can install b2share for development with pip:
 
+.. code-block:: console
+    
+    $ pip install -r requirements.txt
+    $ pip install -e .[all]
+
+and start all services.
+
+B2Share requires some configuration as mentioned in section 1.1 of this document so
+make sure to follow the steps exporting the enviroment variables, and the additional ones
+required for local installations:
+
+.. code-block:: console
+    
+    $ export B2SHARE_UI_PATH=<path-to-b2share-repository>/webui/app
+    $ export B2SHARE_SQLALCHEMY_DATABASE_URI=postgresql+psycopg2://$B2SHARE_POSTGRESQL_USER:$B2SHARE_POSTGRESQL_PASSWORD@localhost:5432/$B2SHARE_POSTGRESQL_DBNAME
+
+Finally, create the DB:
+
+.. code-block:: console
+
+    $ b2share upgrade run
+
+create the Elasticsearch indices and load the templates:
+
+.. code-block:: console
+    
+    $ b2share index init
+
+.. code-block:: console
+    
+    $ b2share schemas init
 
-Then start the ``run_demo.sh`` script:
+and start B2Share with:
 
 .. code-block:: console
 
-    $ chmod +x ./run_demo.sh
-    $ ./run_demo.sh
+    $ b2share run
 
-The script will create a python virtualenv, clone the master branch of
-B2SHARE into it, install the necessary python packages, build the web UI and
-start the Flask server in development mode. B2SHARE should be available at
-http://localhost:5000.
+If you wish to add some demo records and communities, then install the b2share demo application:
+
+.. code-block:: console
+
+    $ cd <path-to-b2share-repository>/demo/
+    $ pip install .
+
+and load the demo data:
+
+.. code-block:: console
+
+    $ b2share demo load_data -vv
 
 Please note that a custom B2ACCESS configuration is also needed, as described
 above. The 'return URL' of the B2ACCESS configuration in this case can be set
 to ``http://localhost:5000/api/oauth/authorized/b2access/``
 
 If working on the web UI, see also: https://github.com/EUDAT-B2SHARE/b2share/wiki/Developer's-corner.
+
+FAQ:
+
+- There is a timeout when trying to create a new record from the UI, or the server hangs when trying to create a draft from the REST API.
+
+This could indicate that the JSONSCHEMAS_HOST is misconfigured. If you are running B2SHARE locally then it should be set to localhost:5000.
+
+- When trying to login the following error is shown:
+
+```
+ERROR
+OAuth Authorization Server got an invalid request.
+
+If you are a user then you can be sure that the web application you was using previously is either misconfigured or buggy.
+
+If you are an administrator or developer the details of the error follows:
+
+The client '<your-b2access-consumer-key>' is unknown
+```
+
+This means that your B2ACCESS credentials are incorrect, or you are working with the staging server and you didn't set USE_STAGING_B2ACCESS=1.
+
+- There is the following error when you run `b2share upgrade run`: sqlalchemy.exc.InvalidRequestError: Naming convention including %(constraint_name)s
+
+If your alembic recipes are unchanged and you also didn't change any of your models.py, this could be due to not having set the B2SHARE_SQLALCHEMY_DATABASE_URI to use Postgresql, and you are using the default which is SQLite, which doesn't support DB migrations with alembic.

b2share/modules/__init__.py

@@ -22,4 +22,4 @@
 # waive the privileges and immunities granted to it by virtue of its status
 # as an Intergovernmental Organization or submit itself to any jurisdiction.
 
-"""B2SHARE"""
+"""B2Share"""

b2share/modules/apiroot/__init__.py

@@ -17,7 +17,7 @@
 # along with B2Share; if not, write to the Free Software Foundation, Inc.,
 # 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
 
-"""B2SHARE"""
+"""B2Share apiroot module."""
 
 from __future__ import absolute_import, print_function
 

b2share/modules/files/__init__.py

@@ -17,7 +17,17 @@
 # along with B2Share; if not, write to the Free Software Foundation, Inc.,
 # 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
 
-"""B2SHARE"""
+"""B2Share files module.
+
+The files module provides the storage class for files with external PIDs
+and background tasks for file checksum verification.
+
+The storage class B2ShareFileStorage is assigned to files with external PIDs
+in order to change the procedure when downloading and
+redirect to the PID instead of starting a file download.
+
+The API for interacting with files is provided directly by invenio-files-rest.
+"""
 
 from __future__ import absolute_import, print_function
 

b2share/modules/oaiserver/__init__.py

@@ -21,7 +21,10 @@
 # waive the privileges and immunities granted to it by virtue of its status
 # as an Intergovernmental Organization or submit itself to any jurisdiction.
 
-"""B2SHARE"""
+"""B2Share oaiserver module.
+
+This module works with invenio-oaiserver to provide a
+command line interface for checking and fixing OAI PMH sets."""
 
 from __future__ import absolute_import, print_function
 

b2share/modules/oauthclient/__init__.py

@@ -22,4 +22,7 @@
 # waive the privileges and immunities granted to it by virtue of its status
 # as an Intergovernmental Organization or submit itself to any jurisdiction.
 
-"""B2SHARE oauth configurations and helpers."""
+"""B2SHARE oauthclient module.
+
+The oauthclient module is used to configure and add helper functions
+to invenio-oauthclient."""

b2share/modules/stats/__init__.py

@@ -17,4 +17,9 @@
 # along with B2Share; if not, write to the Free Software Foundation, Inc.,
 # 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
 
-"""B2SHARE"""
+"""B2Share statistics module.
+
+This module works with invenio-stats. It adds a processor
+which is applied to new events in order to filter out events
+coming from deposits. This way the download statistics are
+calculated only for files of published records."""

b2share/modules/upgrade/__init__.py

@@ -17,7 +17,7 @@
 # along with B2Share; if not, write to the Free Software Foundation, Inc.,
 # 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
 
-"""B2Share upgrade module.
+"""B2SHARE upgrade module.
 
 Command-line interface
 ~~~~~~~~~~~~~~~~~~~~~~