working on documentation

still don't like ReST

ordr2/models/users.py

@@ -54,9 +54,9 @@ class User(Base):
     id = Column(Integer, primary_key=True)
     #: unique user name
     username = Column(Text, nullable=False, unique=True)
-    #: hashed password, see ``ordr2.security``
+    #: hashed password, see :mod:`ordr2.security`
     password_hash = Column(Text, nullable=False)
-    #: role of the user, see ``ordr2.models.users.Role``
+    #: role of the user, see :class:`ordr2.models.users.Role`
     role = Column(Enum(Role), nullable=False)
 
     first_name = Column(Text, nullable=False)

ordr2/security.py

@@ -31,7 +31,15 @@ class AuthenticationPolicy(AuthTktAuthenticationPolicy):
 
 
 def get_user(request):
-    ''' retrieves the user object by the unauthenticated user id '''
+    ''' retrieves the user object by the unauthenticated user id
+
+    :param request:
+        the current request object
+    :type request:
+        pyramid.request.Request
+    :rtype:
+        ordr2.models.users.User or None
+    '''
     user_id = request.unauthenticated_userid
     if user_id is not None:
         user = request.dbsession.query(User).filter_by(id=user_id).first()