merge with better_api_doc

development.ini.old

+###
+# app configuration
+# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+[app:main]
+use = egg:tracim_backend
+
+pyramid.reload_templates = true
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+pyramid.includes =
+    pyramid_debugtoolbar
+
+sqlalchemy.url = sqlite:///%(here)s/tracim.sqlite
+
+retry.attempts = 3
+
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# TRACIM SPECIFIC CONF
+###
+
+### Global
+debug = false
+cache_dir = %(here)s/data
+# preview generator cache directory
+preview_cache_dir = /tmp/tracim/preview/
+# file depot storage
+depot_storage_name = tracim
+depot_storage_dir = %(here)s/depot/
+
+# The following parameters allow to personalize the home page
+# They are html ready (you can put html tags they will be interpreted)
+website.title = TRACIM
+website.title.color = #555
+website.home.subtitle = Default login: email: admin@admin.admin (password: admin@admin.admin)
+website.home.tag_line = <div class="text-center" style="font-weight: bold;">Collaboration, versionning and traceability</div>
+website.home.below_login_form = in case of problem, please contact the administrator.
+# Values may be 'all' or 'folders'
+website.treeview.content = all
+# The following base_url is used for links and icons
+# integrated in the email notifcations
+website.base_url = http://127.0.0.1:8080
+# If config not provided, it will be extracted from website.base_url
+website.server_name = 127.0.0.1
+
+# Specifies if the update of comments and attached files is allowed (by the owner only).
+# Examples:
+#    600 means 10 minutes (ie 600 seconds)
+#   3600 means 1 hour (60x60 seconds)
+#
+# Allowed values:
+#  -1 means that content update is allowed for ever
+#   0 means that content update is not allowed
+#   x means that content update is allowed for x seconds (with x>0)
+content.update.allowed.duration = 3600
+
+# Auth type (internal or ldap)
+auth_type = internal
+# If auth_type is ldap, uncomment following ldap_* parameters
+# LDAP server address
+# ldap_url = ldap://localhost:389
+# Base dn to make queries
+# ldap_base_dn = dc=directory,dc=fsf,dc=org
+# Bind dn to identify the search
+# ldap_bind_dn = cn=admin,dc=directory,dc=fsf,dc=org
+# The bind password
+# ldap_bind_pass = toor
+# Attribute name of user record who contain user login (email)
+# ldap_ldap_naming_attribute = uid
+# Matching between ldap attribute and ldap user field (ldap_attr1=user_field1,ldap_attr2=user_field2,...)
+# ldap_user_attributes = mail=email
+# TLS usage to communicate with your LDAP server
+# ldap_tls = False
+# If True, LDAP own tracim group managment (not available for now!)
+# ldap_group_enabled = False
+# User auth token validity in seconds (used to interfaces like web calendars)
+user.auth_token.validity = 604800
+
+### Mail
+
+# Reset password through email related configuration.
+# These emails will be sent through SMTP
+#
+resetpassword.email_sender = email@sender.com
+resetpassword.smtp_host = smtp.sender
+resetpassword.smtp_port = 25
+resetpassword.smtp_login = smtp.login
+resetpassword.smtp_passwd = smtp.password
+
+email.notification.activated = False
+# email.notification.log_file_path = /tmp/mail-notifications.log
+# email notifications can be sent with the user_id added as an identifier
+# this way email clients like Thunderbird will be able to distinguish
+# notifications generated by a user or another one
+email.notification.from.email = noreply+{user_id}@trac.im
+email.notification.from.default_label = Tracim Notifications
+email.notification.reply_to.email = reply+{content_id}@trac.im
+email.notification.references.email = thread+{content_id}@trac.im
+email.notification.content_update.template.html = %(here)s/tracim/templates/mail/content_update_body_html.mak
+email.notification.content_update.template.text = %(here)s/tracim/templates/mail/content_update_body_text.mak
+email.notification.created_account.template.html = %(here)s/tracim/templates/mail/created_account_body_html.mak
+email.notification.created_account.template.text = %(here)s/tracim/templates/mail/created_account_body_text.mak
+# Note: items between { and } are variable names. Do not remove / rename them
+email.notification.content_update.subject = [{website_title}] [{workspace_label}] {content_label} ({content_status_label})
+email.notification.created_account.subject = [{website_title}] Created account
+# processing_mode may be sync or async
+email.notification.processing_mode = sync
+email.notification.smtp.server = your_smtp_server
+email.notification.smtp.port = 25
+email.notification.smtp.user = your_smtp_user
+email.notification.smtp.password = your_smtp_password
+
+## Email sending configuration
+# processing_mode may be sync or async,
+# with async, please configure redis below
+email.processing_mode = sync
+# email.async.redis.host = localhost
+# email.async.redis.port = 6379
+# email.async.redis.db = 0
+
+# Email reply configuration
+email.reply.activated = False
+email.reply.imap.server = your_imap_server
+email.reply.imap.port = 993
+email.reply.imap.user = your_imap_user
+email.reply.imap.password = your_imap_password
+email.reply.imap.folder = INBOX
+email.reply.imap.use_ssl = true
+email.reply.imap.use_idle = true
+# Re-new connection each 10 minutes
+email.reply.connection.max_lifetime = 600
+# Token for communication between mail fetcher and tracim controller
+email.reply.token = mysecuretoken
+# Delay in seconds between each check
+email.reply.check.heartbeat = 60
+email.reply.use_html_parsing = true
+email.reply.use_txt_parsing = true
+# Lockfile path is required for email_reply feature,
+# it's just an empty file use to prevent concurrent access to imap unseen mail
+email.reply.lockfile_path = %(here)s/email_fetcher.lock
+
+### Radical (CalDav server) configuration
+
+# radicale.server.host = 0.0.0.0
+# radicale.server.port = 5232
+# radicale.server.ssl = false
+radicale.server.filesystem.folder = %(here)s/radicale/collections/
+# radicale.server.allow_origin = *
+# radicale.server.realm_message = Tracim Calendar - Password Required
+## url can be extended like http://127.0.0.1:5232/calendar
+## in this case, you have to create your own proxy behind this url.
+## and update following parameters
+# radicale.client.base_url.host = http://127.0.0.1:5232
+# radicale.client.base_url.prefix = /
+
+### WSGIDAV
+
+wsgidav.config_path = %(here)s/wsgidav.conf
+## url can be extended like 127.0.0.1/webdav
+## in this case, you have to create your own proxy behind this url.
+## Do not set http:// prefix.
+# wsgidav.client.base_url = 127.0.0.1:<WSGIDAV_PORT>
+
+###
+# wsgi server configuration
+###
+
+[server:main]
+use = egg:waitress#main
+listen = localhost:6543
+
+[alembic]
+# path to migration scripts
+script_location = tracim/migration
+
+# template used to generate migration files
+# file_template = %%(rev)s_%%(slug)s
+
+# timezone to use when rendering the date
+# within the migration file as well as the filename.
+# string value is passed to dateutil.tz.gettz()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the
+# "slug" field
+#truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; this defaults
+# to migrate/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path
+# version_locations = %(here)s/bar %(here)s/bat migrate/versions
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+sqlalchemy.url = sqlite:///%(here)s/tracim.sqlite
+
+###
+# logging configuration
+# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
+
+[loggers]
+keys = root, tracim, sqlalchemy, alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+
+[logger_tracim]
+level = DEBUG
+handlers =
+qualname = tracim
+
+[logger_sqlalchemy]
+level = INFO
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
+datefmt = %H:%M:%S

tracim/command/user.py

 #from tracim.lib.daemons import DaemonsManager
 #from tracim.lib.daemons import RadicaleDaemon
 #from tracim.lib.email import get_email_manager
-from tracim.exceptions import UserAlreadyExistError, GroupNotExist
+from tracim.exceptions import UserAlreadyExistError, GroupDoesNotExist
 from tracim.exceptions import NotificationNotSend
 from tracim.exceptions import BadCommandError
 from tracim.lib.core.group import GroupApi
             for group in groups_availables:
                 msg+= "'{}',".format(group)
             self._session.rollback()
-            raise GroupNotExist(msg)
+            raise GroupDoesNotExist(msg)
         return self._group_api.get_one_with_name(name)
 
     def _add_user_to_named_group(

tracim/exceptions.py

     pass
 
 
-class UserNotExist(TracimException):
+class NotificationNotSend(TracimException):
     pass
 
 
-class NotificationNotSend(TracimException):
+class GroupDoesNotExist(TracimError):
+    pass
+
+
+class UserDoesNotExist(TracimException):
     pass
 
 
-class GroupNotExist(TracimError):
+class UserNotFoundInTracimRequest(TracimException):
     pass

tracim/lib/core/group.py

 
 from sqlalchemy.orm.exc import NoResultFound
 
-from tracim.exceptions import GroupNotExist
+from tracim.exceptions import GroupDoesNotExist
 from tracim import CFG
 
 
             session: Session,
             current_user: typing.Optional[User],
             config: CFG
-
     ):
         self._user = current_user
         self._session = session
             group = self._base_query().filter(Group.group_id == group_id).one()
             return group
         except NoResultFound:
-            raise GroupNotExist()
+            raise GroupDoesNotExist()
 
     def get_one_with_name(self, group_name) -> Group:
         try:
             group = self._base_query().filter(Group.group_name == group_name).one()
             return group
         except NoResultFound:
-            raise GroupNotExist()
+            raise GroupDoesNotExist()
 
     def get_all(self):
         return self._base_query().order_by(Group.group_id).all()

tracim/lib/core/user.py

 from sqlalchemy.orm import Session
 
 from tracim import CFG
-from tracim.models.auth import User, Group
+from tracim.models.auth import User
+from tracim.models.auth import Group
 from sqlalchemy.orm.exc import NoResultFound
-from tracim.exceptions import WrongUserPassword, UserNotExist
+from tracim.exceptions import WrongUserPassword, UserDoesNotExist
 from tracim.exceptions import AuthenticationFailed
 from tracim.models.context_models import UserInContext
 
         """
         try:
             user = self._base_query().filter(User.user_id == user_id).one()
-        except NoResultFound:
-            raise UserNotExist()
+        except NoResultFound as exc:
+            raise UserDoesNotExist('User "{}" not found in database'.format(user_id)) from exc  # nopep8
         return user
 
     def get_one_by_email(self, email: str) -> User:
         """
         try:
             user = self._base_query().filter(User.email == email).one()
-        except NoResultFound:
-            raise UserNotExist()
+        except NoResultFound as exc:
+            raise UserDoesNotExist('User "{}" not found in database'.format(email)) from exc  # nopep8
         return user
 
     # FIXME - G.M - 24-04-2018 - Duplicate method with get_one.
         Get current_user
         """
         if not self._user:
-            raise UserNotExist()
+            raise UserDoesNotExist('There is no current user')
         return self._user
 
     def get_all(self) -> typing.Iterable[User]:
             if user.validate_password(password):
                 return user
             else:
-                raise WrongUserPassword()
-        except (WrongUserPassword, NoResultFound, UserNotExist):
-            raise AuthenticationFailed()
+                raise WrongUserPassword('User "{}" password is incorrect'.format(email))  # nopep8
+        except (WrongUserPassword, UserDoesNotExist) as exc:
+            raise AuthenticationFailed('User "{}" authentication failed'.format(email)) from exc  # nopep8
 
     # Actions
 

tracim/lib/core/userworkspace.py

 __author__ = 'damien'
 
 from sqlalchemy.orm import Session
-from tracim.models.auth import User, Group
+from sqlalchemy.orm import Query
+from tracim.models.auth import User
 from tracim.models.data import Workspace
 from tracim.models.data import UserRoleInWorkspace
 from tracim.models.data import RoleType
 
         return role
 
-    def __init__(self,
-                 session: Session,
-                 current_user: typing.Optional[User],
-                 config: CFG):
+    def __init__(
+        self,
+        session: Session,
+        current_user: typing.Optional[User],
+        config: CFG,
+    )-> None:
         self._session = session
         self._user = current_user
         self._config = config
 
-    def _get_one_rsc(self, user_id, workspace_id):
+    def _get_one_rsc(self, user_id: int, workspace_id: int) -> Query:
         """
         :param user_id:
         :param workspace_id:
             filter(UserRoleInWorkspace.workspace_id == workspace_id).\
             filter(UserRoleInWorkspace.user_id == user_id)
 
-    def get_one(self, user_id, workspace_id):
+    def get_one(self, user_id: int, workspace_id: int) -> UserRoleInWorkspace:
         return self._get_one_rsc(user_id, workspace_id).one()
 
     def create_one(
-            self,
-            user: User,
-            workspace: Workspace,
-            role_level: int,
-            with_notif: bool,
-            flush: bool=True
+        self,
+        user: User,
+        workspace: Workspace,
+        role_level: int,
+        with_notif: bool,
+        flush: bool=True
     ) -> UserRoleInWorkspace:
         role = self.create_role()
         role.user_id = user.user_id
             self._session.flush()
         return role
 
-    def delete_one(self, user_id, workspace_id, flush=True):
+    def delete_one(self, user_id: int, workspace_id: int, flush=True) -> None:
         self._get_one_rsc(user_id, workspace_id).delete()
         if flush:
             self._session.flush()
 
-    def _get_all_for_user(self, user_id):
+    def _get_all_for_user(self, user_id) -> typing.List[UserRoleInWorkspace]:
         return self._session.query(UserRoleInWorkspace)\
             .filter(UserRoleInWorkspace.user_id == user_id)
 
-    def get_all_for_user(self, user: User):
+    def get_all_for_user(self, user: User) -> typing.List[UserRoleInWorkspace]:
         return self._get_all_for_user(user.user_id).all()
 
     def get_all_for_user_order_by_workspace(
-            self,
-            user_id: int
-    ) -> UserRoleInWorkspace:
+        self,
+        user_id: int
+    ) -> typing.List[UserRoleInWorkspace]:
         return self._get_all_for_user(user_id)\
             .join(UserRoleInWorkspace.workspace).order_by(Workspace.label).all()
 
-    def get_all_for_workspace(self, workspace:Workspace):
+    def get_all_for_workspace(
+        self,
+        workspace:Workspace
+    ) -> typing.List[UserRoleInWorkspace]:
         return self._session.query(UserRoleInWorkspace)\
             .filter(UserRoleInWorkspace.workspace_id == workspace.workspace_id).all()  # nopep8
 
-    def save(self, role: UserRoleInWorkspace):
+    def save(self, role: UserRoleInWorkspace) -> None:
         self._session.flush()
 
+    # TODO - G.M - 07-06-2018 - [Cleanup] Check if this method is already needed
     @classmethod
-    def get_roles_for_select_field(cls):
+    def get_roles_for_select_field(cls) -> typing.List[RoleType]:
         """
 
         :return: list of DictLikeClass instances representing available Roles

tracim/lib/utils/authentification.py

 from sqlalchemy.orm.exc import NoResultFound
 
 from tracim import TracimRequest
-from tracim.exceptions import UserNotExist
+from tracim.exceptions import UserDoesNotExist
 from tracim.lib.core.user import UserApi
 from tracim.models import User
 
         if not login:
             return None
         user = uapi.get_one_by_email(login)
-    except (NoResultFound, UserNotExist):
+    except (NoResultFound, UserDoesNotExist):
         return None
     return user

tracim/lib/utils/authorization.py

             raise InsufficientUserWorkspaceRole()
 
         return wrapper
-    return decorator
+    return decorator

tracim/lib/utils/request.py

 from pyramid.request import Request
 from sqlalchemy.orm.exc import NoResultFound
 
-from tracim.exceptions import NotAuthentificated, UserNotExist
+
+from tracim.exceptions import NotAuthentificated
+from tracim.exceptions import UserNotFoundInTracimRequest
+from tracim.exceptions import UserDoesNotExist
 from tracim.exceptions import WorkspaceNotFound
 from tracim.exceptions import ImmutableAttribute
 from tracim.lib.core.user import UserApi
         if 'user_id' in request.matchdict:
             login = request.matchdict['user_id']
         if not login:
-            raise UserNotExist('no user_id found, incorrect request ?')
+            raise UserNotFoundInTracimRequest('You request a candidate user but the context not permit to found one')  # nopep8
         user = uapi.get_one(login)
-    except NoResultFound:
-        raise NotAuthentificated('User not found')
+    except UserNotFoundInTracimRequest as exc:
+        raise UserDoesNotExist('User {} not found'.format(login)) from exc
     return user
 
 
     try:
         login = request.authenticated_userid
         if not login:
-            raise NotAuthentificated('not authenticated user_id,'
-                                     'Failed Authentification ?')
+            raise UserNotFoundInTracimRequest('You request a current user but the context not permit to found one')  # nopep8
         user = uapi.get_one_by_email(login)
-    except NoResultFound:
-        raise NotAuthentificated('User not found')
+    except (UserDoesNotExist, UserNotFoundInTracimRequest) as exc:
+        raise NotAuthentificated('User {} not found'.format(login)) from exc
     return user
 
 

tracim/models/applications.py

         self.main_route = main_route
 
 
-# TODO - G.M - 21-05-2018 Do not rely on hardcoded app list
 # default apps
 calendar = Application(
     label='Calendar',
     main_route='/#/workspaces/{workspace_id}/contents?type=file',
 )
 
-pagemarkdownplus = Application(
-    label='Rich Markdown Files',  # TODO - G.M - 24-05-2018 - Check label
-    slug='contents/pagemarkdownplus',
+markdownpluspage = Application(
+    label='Markdown Plus Documents',  # TODO - G.M - 24-05-2018 - Check label
+    slug='contents/markdownpluspage',
     icon='file-code',
     hexcolor='#f12d2d',
     is_active=True,
     config={},
-    main_route='/#/workspaces/{workspace_id}/contents?type=pagemarkdownplus',
+    main_route='/#/workspaces/{workspace_id}/contents?type=markdownpluspage',
 )
 
-pagehtml = Application(
+htmlpage = Application(
     label='Text Documents',  # TODO - G.M - 24-05-2018 - Check label
-    slug='contents/pagehtml',
+    slug='contents/htmlpage',
     icon='file-text-o',
     hexcolor='#3f52e3',
     is_active=True,
     config={},
-    main_route='/#/workspaces/{workspace_id}/contents?type=pagehtml',
+    main_route='/#/workspaces/{workspace_id}/contents?type=htmlpage',
 )
+# TODO - G.M - 08-06-2018 - This is hardcoded lists of app, make this dynamic.
 # List of applications
 applications = [
-    pagehtml,
-    pagemarkdownplus,
+    htmlpage,
+    markdownpluspage,
     file,
     thread,
     calendar,

tracim/models/auth.py

 class Profile(object):
     """This model is the "max" group associated to a given user."""
 
-    _NAME = [Group.TIM_NOBODY_GROUPNAME,
-             Group.TIM_USER_GROUPNAME,
-             Group.TIM_MANAGER_GROUPNAME,
-             Group.TIM_ADMIN_GROUPNAME]
-
-    _IDS = [Group.TIM_NOBODY,
-            Group.TIM_USER,
-            Group.TIM_MANAGER,
-            Group.TIM_ADMIN]
+    _NAME = [
+        Group.TIM_NOBODY_GROUPNAME,
+        Group.TIM_USER_GROUPNAME,
+        Group.TIM_MANAGER_GROUPNAME,
+        Group.TIM_ADMIN_GROUPNAME,
+    ]
+
+    _IDS = [
+        Group.TIM_NOBODY,
+        Group.TIM_USER,
+        Group.TIM_MANAGER,
+        Group.TIM_ADMIN,
+    ]
 
     # TODO - G.M - 18-04-2018 [Cleanup] Drop this
     # _LABEL = [l_('Nobody'),

tracim/models/context_models.py

 from tracim.models import User
 from tracim.models.auth import Profile
 from tracim.models.data import Workspace, UserRoleInWorkspace
-from tracim.models.workspace_menu_entries import default_workspace_menu_entry, \
-    WorkspaceMenuEntry
+from tracim.models.workspace_menu_entries import default_workspace_menu_entry
+from tracim.models.workspace_menu_entries import WorkspaceMenuEntry
 
 
 class LoginCredentials(object):

tracim/models/data.py

     WORKSPACE_MANAGER = 8
 
     # TODO - G.M - 10-04-2018 - [Cleanup] Drop this
-
-    SLUG = dict()
-    SLUG[NOT_APPLICABLE] = 'not_applicable'
-    SLUG[READER] = 'reader'
-    SLUG[CONTRIBUTOR] = 'contributor'
-    SLUG[CONTENT_MANAGER] = 'content_manager'
-    SLUG[WORKSPACE_MANAGER] = 'workspace_manager'
+    SLUG = {
+        NOT_APPLICABLE: 'not_applicable',
+        READER: 'reader',
+        CONTRIBUTOR: 'contributor',
+        CONTENT_MANAGER: 'content_manager',
+        WORKSPACE_MANAGER: 'workspace_manager',
+    }
 
     LABEL = dict()
     LABEL[0] = l_('N/A')

tracim/models/workspace_menu_entries.py

         self.hexcolor = hexcolor
         self.icon = icon
 
-
 dashboard_menu_entry = WorkspaceMenuEntry(
   slug='dashboard',
   label='Dashboard',
   icon="",
 )
 
-
+# TODO - G.M - 08-06-2018 - This is hardcoded default menu entry,
+#  of app, make this dynamic (and loaded from application system)
 def default_workspace_menu_entry(
     workspace: Workspace,
 )-> typing.List[WorkspaceMenuEntry]:

tracim/tests/commands/test_commands.py

 # -*- coding: utf-8 -*-
 import os
 import subprocess
-
 import pytest
-import transaction
-from pkg_resources import load_entry_point
-from sqlalchemy.orm.exc import NoResultFound
-
 import tracim
 from tracim.command import TracimCLI
-from tracim.command.user import UserCommand
-from tracim.exceptions import UserAlreadyExistError, BadCommandError, \
-    GroupNotExist, UserNotExist
+from tracim.exceptions import UserAlreadyExistError
+from tracim.exceptions import BadCommandError
+from tracim.exceptions import GroupDoesNotExist
+from tracim.exceptions import UserDoesNotExist
 from tracim.lib.core.user import UserApi
 from tracim.tests import CommandFunctionalTest
 
             session=self.session,
             config=self.app_config,
         )
-        with pytest.raises(UserNotExist):
+        with pytest.raises(UserDoesNotExist):
             api.get_one_by_email('command_test@user')
         app = TracimCLI()
         result = app.run([
             session=self.session,
             config=self.app_config,
         )
-        with pytest.raises(UserNotExist):
+        with pytest.raises(UserDoesNotExist):
             api.get_one_by_email('command_test@user')
         app = TracimCLI()
         result = app.run([
             config=self.app_config,
         )
         app = TracimCLI()
-        with pytest.raises(GroupNotExist):
+        with pytest.raises(GroupDoesNotExist):
             result = app.run([
                 'user', 'create',
                 '-c', 'tests_configs.ini#command_test',

tracim/tests/functional/test_session.py

         assert res.json_body['created']
         assert res.json_body['is_active']
         assert res.json_body['profile']
-        assert isinstance(res.json_body['profile']['id'], int)
         assert res.json_body['profile']['slug'] == 'administrators'
         assert res.json_body['caldav_url'] is None
         assert res.json_body['avatar_url'] is None
         assert res.json_body['created']
         assert res.json_body['is_active']
         assert res.json_body['profile']
-        assert isinstance(res.json_body['profile']['id'], int)
         assert res.json_body['profile']['slug'] == 'administrators'
         assert res.json_body['caldav_url'] is None
         assert res.json_body['avatar_url'] is None

tracim/tests/functional/test_system.py

         res = res.json_body
         application = res[0]
         assert application['label'] == "Text Documents"
-        assert application['slug'] == 'contents/pagehtml'
+        assert application['slug'] == 'contents/htmlpage'
         assert application['icon'] == 'file-text-o'
         assert application['hexcolor'] == '#3f52e3'
         assert application['is_active'] is True
         assert 'config' in application
         application = res[1]
-        assert application['label'] == "Rich Markdown Files"
-        assert application['slug'] == 'contents/pagemarkdownplus'
+        assert application['label'] == "Markdown Plus Documents"
+        assert application['slug'] == 'contents/markdownpluspage'
         assert application['icon'] == 'file-code'
         assert application['hexcolor'] == '#f12d2d'
         assert application['is_active'] is True

tracim/tests/functional/test_user.py

         assert sidebar_entry['icon'] == ""
 
         sidebar_entry = workspace['sidebar_entries'][2]
-        assert sidebar_entry['slug'] == 'contents/pagehtml'
+        assert sidebar_entry['slug'] == 'contents/htmlpage'
         assert sidebar_entry['label'] == 'Text Documents'
-        assert sidebar_entry['route'] == '/#/workspaces/1/contents?type=pagehtml'  # nopep8
+        assert sidebar_entry['route'] == '/#/workspaces/1/contents?type=htmlpage'  # nopep8
         assert sidebar_entry['hexcolor'] == "#3f52e3"
         assert sidebar_entry['icon'] == "file-text-o"
 
         sidebar_entry = workspace['sidebar_entries'][3]
-        assert sidebar_entry['slug'] == 'contents/pagemarkdownplus'
-        assert sidebar_entry['label'] == 'Rich Markdown Files'
-        assert sidebar_entry['route'] == "/#/workspaces/1/contents?type=pagemarkdownplus"    # nopep8
+        assert sidebar_entry['slug'] == 'contents/markdownpluspage'
+        assert sidebar_entry['label'] == 'Markdown Plus Documents'
+        assert sidebar_entry['route'] == "/#/workspaces/1/contents?type=markdownpluspage"    # nopep8
         assert sidebar_entry['hexcolor'] == "#f12d2d"
         assert sidebar_entry['icon'] == "file-code"
 

tracim/tests/functional/test_workspaces.py

         assert sidebar_entry['icon'] == ""
 
         sidebar_entry = workspace['sidebar_entries'][2]
-        assert sidebar_entry['slug'] == 'contents/pagehtml'
+        assert sidebar_entry['slug'] == 'contents/htmlpage'
         assert sidebar_entry['label'] == 'Text Documents'
-        assert sidebar_entry['route'] == '/#/workspaces/1/contents?type=pagehtml'  # nopep8
+        assert sidebar_entry['route'] == '/#/workspaces/1/contents?type=htmlpage'  # nopep8
         assert sidebar_entry['hexcolor'] == "#3f52e3"
         assert sidebar_entry['icon'] == "file-text-o"
 
         sidebar_entry = workspace['sidebar_entries'][3]
-        assert sidebar_entry['slug'] == 'contents/pagemarkdownplus'
-        assert sidebar_entry['label'] == 'Rich Markdown Files'
-        assert sidebar_entry['route'] == "/#/workspaces/1/contents?type=pagemarkdownplus"    # nopep8
+        assert sidebar_entry['slug'] == 'contents/markdownpluspage'
+        assert sidebar_entry['label'] == 'Markdown Plus Documents'
+        assert sidebar_entry['route'] == "/#/workspaces/1/contents?type=markdownpluspage"    # nopep8
         assert sidebar_entry['hexcolor'] == "#f12d2d"
         assert sidebar_entry['icon'] == "file-code"
 
         assert len(res) == 2
         user_role = res[0]
         assert user_role['role_slug'] == 'workspace_manager'
-        assert user_role['role_id'] == 8
         assert user_role['user_id'] == 1
         assert user_role['workspace_id'] == 1
         assert user_role['user']['display_name'] == 'Global manager'

tracim/tests/library/test_group_api.py

 # coding=utf-8
 import pytest
 
-from tracim.exceptions import GroupNotExist
+from tracim.exceptions import GroupDoesNotExist
 from tracim.lib.core.group import GroupApi
 from tracim.tests import DefaultTest
 from tracim.fixtures.users_and_groups import Base as BaseFixture
             session=self.session,
             config=self.app_config,
         )
-        with pytest.raises(GroupNotExist):
+        with pytest.raises(GroupDoesNotExist):
             group = api.get_one(10)
 
     def test_unit__get_one_group_with_name__nominal_case(self) -> None:
             session=self.session,
             config=self.app_config,
         )
-        with pytest.raises(GroupNotExist):
+        with pytest.raises(GroupDoesNotExist):
             group = api.get_one_with_name('unknown_group')
 
     def test_unit__get_all__ok__nominal_case(self):

tracim/tests/library/test_user_api.py

 
 import transaction
 
-from tracim.exceptions import UserNotExist, AuthenticationFailed
+from tracim.exceptions import UserDoesNotExist, AuthenticationFailed
 from tracim.lib.core.user import UserApi
 from tracim.models import User
 from tracim.models.context_models import UserInContext
             session=self.session,
             config=self.config,
         )
-        with pytest.raises(UserNotExist):
+        with pytest.raises(UserDoesNotExist):
             api.get_one_by_email('unknown')
 
     def test_unit__get_all__ok__nominal_case(self):
             session=self.session,
             config=self.config,
         )
-        with pytest.raises(UserNotExist):
+        with pytest.raises(UserDoesNotExist):
             api.get_current_user()
 
     def test_unit__authenticate_user___ok__nominal_case(self):

tracim/views/core_api/schemas.py

 
 
 class ProfileSchema(marshmallow.Schema):
-    id = marshmallow.fields.Int(dump_only=True, validate=OneOf(Profile._IDS))
-    slug = marshmallow.fields.String(attribute='name', validate=OneOf(Profile._NAME))
+    slug = marshmallow.fields.String(
+        attribute='name',
+        validate=OneOf(Profile._NAME),
+        example='managers',
+    )
+
+    class Meta:
+        description = 'User Profile, give user right on whole Tracim instance.'
 
 
 class UserSchema(marshmallow.Schema):
 
-    user_id = marshmallow.fields.Int(dump_only=True)
-    email = marshmallow.fields.Email(required=True)
-    display_name = marshmallow.fields.String()
-    created = marshmallow.fields.DateTime(format='iso8601')
-    is_active = marshmallow.fields.Bool()
+    user_id = marshmallow.fields.Int(dump_only=True, example=3)
+    email = marshmallow.fields.Email(
+        required=True,
+        example='suri.cate@algoo.fr'
+    )
+    display_name = marshmallow.fields.String(
+        example='Suri Cate',
+    )
+    created = marshmallow.fields.DateTime(
+        format='iso8601',
+        description='User account creation date (iso8601 format).',
+    )
+    is_active = marshmallow.fields.Bool(
+        example=True,
+         # TODO - G.M - Explains this value.
+    )
     # TODO - G.M - 17-04-2018 - Restrict timezone values
-    timezone = marshmallow.fields.String()
+    timezone = marshmallow.fields.String(
+        example="Paris/Europe",
+    )
     # TODO - G.M - 17-04-2018 - check this, relative url allowed ?
     caldav_url = marshmallow.fields.Url(
         allow_none=True,
         relative=True,
-        attribute='calendar_url'
+        attribute='calendar_url',
+        example="/api/v2/calendar/user/3.ics/",
+        description="The url for calendar CalDAV direct access",
+    )
+    avatar_url = marshmallow.fields.Url(
+        allow_none=True,
+        example="/api/v2/assets/avatars/suri-cate.jpg",
+        description="avatar_url is the url to the image file. "
+                    "If no avatar, then set it to null "
+                    "(and frontend will interpret this with a default avatar)",
     )
-    avatar_url = marshmallow.fields.Url(allow_none=True)
     profile = marshmallow.fields.Nested(
         ProfileSchema,
         many=False,
     )
 
+    class Meta:
+        description = 'User account of Tracim'
+
 
 class UserIdPathSchema(marshmallow.Schema):
-    user_id = marshmallow.fields.Int()
+    user_id = marshmallow.fields.Int(example=3)
 
 
 class WorkspaceIdPathSchema(marshmallow.Schema):
-    workspace_id = marshmallow.fields.Int()
+    workspace_id = marshmallow.fields.Int(example=4)
 
 
 class BasicAuthSchema(marshmallow.Schema):
 
-    email = marshmallow.fields.Email(required=True)
-    password = marshmallow.fields.String(required=True, load_only=True)
+    email = marshmallow.fields.Email(
+        example='suri.cate@algoo.fr',
+        required=True
+    )
+    password = marshmallow.fields.String(
+        example='8QLa$<w',
+        required=True,
+        load_only=True,
+    )
+
+    class Meta:
+        description = 'Entry for HTTP Basic Auth'
 
     @post_load
     def make_login(self, data):
 
 
 class NoContentSchema(marshmallow.Schema):
+
+    class Meta:
+        description = 'Empty Schema'
     pass
 
 
 class WorkspaceMenuEntrySchema(marshmallow.Schema):
-    slug = marshmallow.fields.String()
-    label = marshmallow.fields.String()
-    route = marshmallow.fields.String()
-    hexcolor = marshmallow.fields.String()
-    icon = marshmallow.fields.String()
-
-
-class WorkspaceSchema(marshmallow.Schema):
-    id = marshmallow.fields.Int()
-    slug = marshmallow.fields.String()
-    label = marshmallow.fields.String()
-    description = marshmallow.fields.String()
-    sidebar_entries = marshmallow.fields.Nested(
-        WorkspaceMenuEntrySchema,
-        many=True,
+    slug = marshmallow.fields.String(example='markdown-pages')
+    label = marshmallow.fields.String(example='Markdown Documents')
+    route = marshmallow.fields.String(
+        example='/#/workspace/{workspace_id}/contents/?type=mardown-page',
+        description='the route is the frontend route. '
+                    'It may include workspace_id '
+                    'which must be replaced on backend size '
+                    '(the route must be ready-to-use)'
+    )
+    icon = marshmallow.fields.String(
+        example='file-text-o',
+        description='CSS class of the icon. Example: file-o for using Fontawesome file-text-o icon',  # nopep8
+    )
+    hexcolor = marshmallow.fields.String(
+        example='#F0F9DC',
+        description='Hexadecimal color of the entry.'
     )
 
+    class Meta:
+        description = 'Entry element of a workspace menu'
+
 
 class WorkspaceDigestSchema(marshmallow.Schema):
-    id = marshmallow.fields.Int()
-    label = marshmallow.fields.String()
+    id = marshmallow.fields.Int(example=4)
+    label = marshmallow.fields.String(example='Intranet')
     sidebar_entries = marshmallow.fields.Nested(
         WorkspaceMenuEntrySchema,
         many=True,
     )
 
+    class Meta:
+        description = 'Digest of workspace informations'
+
+
+class WorkspaceSchema(WorkspaceDigestSchema):
+    slug = marshmallow.fields.String(example='intranet')
+    description = marshmallow.fields.String(example='All intranet data.')
+
+    class Meta:
+        description = 'Full workspace informations'
+
 
 class WorkspaceMemberSchema(marshmallow.Schema):
-    role_id = marshmallow.fields.Int(validate=OneOf(UserRoleInWorkspace.get_all_role_values()))  # nopep8
-    role_slug = marshmallow.fields.String(validate=OneOf(UserRoleInWorkspace.get_all_role_slug()))  # nopep8
-    user_id = marshmallow.fields.Int()
-    workspace_id = marshmallow.fields.Int()
+    role_slug = marshmallow.fields.String(
+        example='contributor',
+        validate=OneOf(UserRoleInWorkspace.get_all_role_slug())
+    )
+    user_id = marshmallow.fields.Int(example=3)
+    workspace_id = marshmallow.fields.Int(example=4)
     user = marshmallow.fields.Nested(
         UserSchema(only=('display_name', 'avatar_url'))
     )
 
+    class Meta:
+        description = 'Workspace Member information'
+
 
 class ApplicationConfigSchema(marshmallow.Schema):
     pass
 
 
 class ApplicationSchema(marshmallow.Schema):
-    label = marshmallow.fields.String()
-    slug = marshmallow.fields.String()
-    icon = marshmallow.fields.String()
-    hexcolor = marshmallow.fields.String()
-    is_active = marshmallow.fields.Boolean()
+    label = marshmallow.fields.String(example='Calendar')
+    slug = marshmallow.fields.String(example='calendar')
+    icon = marshmallow.fields.String(
+        example='file-o',
+        description='CSS class of the icon. Example: file-o for using Fontawesome file-o icon',  # nopep8
+    )
+    hexcolor = marshmallow.fields.String(
+        example='#FF0000',
+        description='HTML encoded color associated to the application. Example:#FF0000 for red'  # nopep8
+    )
+    is_active = marshmallow.fields.Boolean(
+        example=True,
+        description='if true, the application is in use in the context',
+    )
     config = marshmallow.fields.Nested(
         ApplicationConfigSchema,
     )
+
+    class Meta:
+        description = 'Tracim Application informations'

tracim/views/core_api/user_controller.py

     from http import client as HTTPStatus
 
 from tracim import hapic, TracimRequest
-from tracim.exceptions import NotAuthentificated, InsufficientUserProfile, \
-    UserNotExist
-from tracim.lib.core.user import UserApi
+
+from tracim.exceptions import NotAuthentificated
+from tracim.exceptions import InsufficientUserProfile
+from tracim.exceptions import UserDoesNotExist
 from tracim.lib.core.workspace import WorkspaceApi
 from tracim.views.controllers import Controller
-from tracim.views.core_api.schemas import UserIdPathSchema, \
-    WorkspaceDigestSchema
+from tracim.views.core_api.schemas import UserIdPathSchema
+from tracim.views.core_api.schemas import WorkspaceDigestSchema
 
 
 class UserController(Controller):
     @hapic.with_api_doc()
     @hapic.handle_exception(NotAuthentificated, HTTPStatus.UNAUTHORIZED)
     @hapic.handle_exception(InsufficientUserProfile, HTTPStatus.FORBIDDEN)
-    @hapic.handle_exception(UserNotExist, HTTPStatus.NOT_FOUND)
+    @hapic.handle_exception(UserDoesNotExist, HTTPStatus.NOT_FOUND)
     @require_same_user_or_profile(Group.TIM_ADMIN)
     @hapic.input_path(UserIdPathSchema())
     @hapic.output_body(WorkspaceDigestSchema(many=True),)
             session=request.dbsession,
             config=app_config,
         )
+        
+        workspaces = wapi.get_all_for_user(request.candidate_user)
         return [
             WorkspaceInContext(workspace, request.dbsession, app_config)
-            for workspace in wapi.get_all_for_user(request.candidate_user)
+            for workspace in workspaces
         ]
 
     def bind(self, configurator: Configurator) -> None:

tracim/views/core_api/workspace_controller.py

 
 from tracim.lib.core.userworkspace import RoleApi
 from tracim.lib.utils.authorization import require_workspace_role
-from tracim.models.context_models import WorkspaceInContext, \
-    UserRoleWorkspaceInContext
+from tracim.models.context_models import WorkspaceInContext
+from tracim.models.context_models import UserRoleWorkspaceInContext
 from tracim.models.data import UserRoleInWorkspace
 
 try:  # Python 3.5+
     from http import client as HTTPStatus
 
 from tracim import hapic, TracimRequest
-from tracim.exceptions import NotAuthentificated, InsufficientUserProfile, \
-    WorkspaceNotFound
+from tracim.exceptions import NotAuthentificated
+from tracim.exceptions import InsufficientUserProfile
+from tracim.exceptions import WorkspaceNotFound
 from tracim.lib.core.user import UserApi
 from tracim.lib.core.workspace import WorkspaceApi
 from tracim.views.controllers import Controller
-from tracim.views.core_api.schemas import WorkspaceSchema, UserSchema, \
-    WorkspaceIdPathSchema, WorkspaceMemberSchema
-
+from tracim.views.core_api.schemas import WorkspaceSchema
+from tracim.views.core_api.schemas import UserSchema
+from tracim.views.core_api.schemas import WorkspaceIdPathSchema
+from tracim.views.core_api.schemas import WorkspaceMemberSchema
 
 class WorkspaceController(Controller):
 
             session=request.dbsession,
             config=app_config,
         )
+        
+        roles = rapi.get_all_for_workspace(request.current_workspace)
         return [
             rapi.get_user_role_workspace_with_context(user_role)
-            for user_role in rapi.get_all_for_workspace(request.current_workspace)
+            for user_role in roles
         ]
 
     def bind(self, configurator: Configurator) -> None:
         """
-        Create all routes and views using pyramid configurator
-        for this controller
+        Create all routes and views using
+        pyramid configurator for this controller
         """
 
         # Applications