Add some docs using sphinx autodoc

cas_server/forms.py

@@ -19,20 +19,33 @@ import cas_server.models as models
 
 
 class WarnForm(forms.Form):
-    """Form used on warn page before emiting a ticket"""
+    """
+        Bases: :class:`django.forms.Form`
+
+        Form used on warn page before emiting a ticket
+    """
+
+    #: The service url for which the user want a ticket
     service = forms.CharField(widget=forms.HiddenInput(), required=False)
+    #: Is the service asking the authentication renewal ?
     renew = forms.BooleanField(widget=forms.HiddenInput(), required=False)
+    #: Url to redirect to if the authentication fail (user not authenticated or bad service)
     gateway = forms.CharField(widget=forms.HiddenInput(), required=False)
     method = forms.CharField(widget=forms.HiddenInput(), required=False)
+    #: ``True`` if the user has been warned of the ticket emission
     warned = forms.BooleanField(widget=forms.HiddenInput(), required=False)
+    #: A valid LoginTicket to prevent POST replay
     lt = forms.CharField(widget=forms.HiddenInput(), required=False)
 
 
 class FederateSelect(forms.Form):
     """
-        Form used on the login page when CAS_FEDERATE is True
-        allowing the user to choose a identity provider.
+        Bases: :class:`django.forms.Form`
+
+        Form used on the login page when ``settings.CAS_FEDERATE`` is ``True``
+        allowing the user to choose an identity provider.
     """
+    #: The providers the user can choose to be used as authentication backend
     provider = forms.ModelChoiceField(
         queryset=models.FederatedIendityProvider.objects.filter(display=True).order_by(
             "pos",
@@ -42,27 +55,49 @@ class FederateSelect(forms.Form):
         to_field_name="suffix",
         label=_('Identity provider'),
     )
+    #: The service url for which the user want a ticket
     service = forms.CharField(label=_('service'), widget=forms.HiddenInput(), required=False)
     method = forms.CharField(widget=forms.HiddenInput(), required=False)
+    #: A checkbox to remember the user choices of :attr:`provider<FederateSelect.provider>`
     remember = forms.BooleanField(label=_('Remember the identity provider'), required=False)
+    #: A checkbox to ask to be warn before emiting a ticket for another service
     warn = forms.BooleanField(label=_('warn'), required=False)
+    #: Is the service asking the authentication renewal ?
     renew = forms.BooleanField(widget=forms.HiddenInput(), required=False)
 
 
 class UserCredential(forms.Form):
-    """Form used on the login page to retrive user credentials"""
+    """
+         Bases: :class:`django.forms.Form`
+
+         Form used on the login page to retrive user credentials
+     """
+    #: The user username
     username = forms.CharField(label=_('login'))
+    #: The service url for which the user want a ticket
     service = forms.CharField(label=_('service'), widget=forms.HiddenInput(), required=False)
+    #: The user password
     password = forms.CharField(label=_('password'), widget=forms.PasswordInput)
+    #: A valid LoginTicket to prevent POST replay
     lt = forms.CharField(widget=forms.HiddenInput(), required=False)
     method = forms.CharField(widget=forms.HiddenInput(), required=False)
+    #: A checkbox to ask to be warn before emiting a ticket for another service
     warn = forms.BooleanField(label=_('warn'), required=False)
+    #: Is the service asking the authentication renewal ?
     renew = forms.BooleanField(widget=forms.HiddenInput(), required=False)
 
     def __init__(self, *args, **kwargs):
         super(UserCredential, self).__init__(*args, **kwargs)
 
     def clean(self):
+        """
+            Validate that the submited :attr:`username` and :attr:`password` are valid
+
+            :raises django.forms.ValidationError: if the :attr:`username` and :attr:`password`
+                are not valid.
+            :return: The cleaned POST data
+            :rtype: dict
+        """
         cleaned_data = super(UserCredential, self).clean()
         auth = utils.import_attr(settings.CAS_AUTH_CLASS)(cleaned_data.get("username"))
         if auth.test_password(cleaned_data.get("password")):
@@ -73,17 +108,51 @@ class UserCredential(forms.Form):
 
 
 class FederateUserCredential(UserCredential):
-    """Form used on the login page to retrive user credentials"""
+    """
+        Bases: :class:`UserCredential`
+
+        Form used on a auto submited page for linking the views
+        :class:`FederateAuth<cas_server.views.FederateAuth>` and
+        :class:`LoginView<cas_server.views.LoginView>`.
+
+        On successful authentication on a provider, in the view
+        :class:`FederateAuth<cas_server.views.FederateAuth>` a
+        :class:`FederatedUser<cas_server.models.FederatedUser>` is created by
+        :meth:`cas_server.federate.CASFederateValidateUser.verify_ticket` and the user is redirected
+        to :class:`LoginView<cas_server.views.LoginView>`. This form is then automatically filled
+        with infos matching the created :class:`FederatedUser<cas_server.models.FederatedUser>`
+        using the ``ticket`` as one time password and submited using javascript. If javascript is
+        not enabled, a connect button is displayed.
+
+        This stub authentication form, allow to implement the federated mode with very few
+        modificatons to the :class:`LoginView<cas_server.views.LoginView>` view.
+    """
+    #: the user username with the ``@`` component
     username = forms.CharField(widget=forms.HiddenInput())
+    #: The service url for which the user want a ticket
     service = forms.CharField(widget=forms.HiddenInput(), required=False)
+    #: The ``ticket`` used to authenticate the user against a provider
     password = forms.CharField(widget=forms.HiddenInput())
+    #: alias of :attr:`password`
     ticket = forms.CharField(widget=forms.HiddenInput())
+    #: A valid LoginTicket to prevent POST replay
     lt = forms.CharField(widget=forms.HiddenInput(), required=False)
     method = forms.CharField(widget=forms.HiddenInput(), required=False)
+    #: Has the user asked to be warn before emiting a ticket for another service
     warn = forms.BooleanField(widget=forms.HiddenInput(), required=False)
+    #: Is the service asking the authentication renewal ?
     renew = forms.BooleanField(widget=forms.HiddenInput(), required=False)
 
     def clean(self):
+        """
+            Validate that the submited :attr:`username` and :attr:`password` are valid using
+            the :class:`CASFederateAuth<cas_server.auth.CASFederateAuth>` auth class.
+
+            :raises django.forms.ValidationError: if the :attr:`username` and :attr:`password`
+                do not correspond to a :class:`FederatedUser<cas_server.models.FederatedUser>`.
+            :return: The cleaned POST data
+            :rtype: dict
+        """
         cleaned_data = super(FederateUserCredential, self).clean()
         try:
             user = models.FederatedUser.get_from_federated_username(cleaned_data["username"])
@@ -99,7 +168,11 @@ class FederateUserCredential(UserCredential):
 
 
 class TicketForm(forms.ModelForm):
-    """Form for Tickets in the admin interface"""
+    """
+        Bases: :class:`django.forms.ModelForm`
+
+        Form for Tickets in the admin interface
+    """
     class Meta:
         model = models.Ticket
         exclude = []