Add views and forms documentation

main/forms.py

@@ -7,13 +7,14 @@ from main.models import UserProfile
 class CustomRegistrationForm(RegistrationFormUniqueEmail):
     """
         Форма для регистрации :class:`django_registration.forms.RegistrationFormUniqueEmail`
-        с добавлением bootstrap-класса 'form-control'
 
-        :param password_zen: Поле для ввода пароля от Zendesk
+        с добавлением bootstrap-класса "form-control"
-        :type password_zen: :class:`django.forms.CharField`
+
+        :param visible_fields.email: Поле для ввода email, зарегистирированного на Zendesk
+        :type visible_fields.email: :class:`django_registration.forms.RegistrationFormUniqueEmail`
     """
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs) -> RegistrationFormUniqueEmail:
         super().__init__(*args, **kwargs)
         for visible in self.visible_fields():
             if visible.field.widget.attrs.get('class', False):
@@ -30,10 +31,10 @@ class CustomRegistrationForm(RegistrationFormUniqueEmail):
 
 class AdminPageUsers(forms.Form):
     """
-        Форма для установки статуса
+        Форма для установки статусов engineer или light_agent пользователям
 
-        :param password_zen: Поле для ввода пароля от Zendesk
+        :param users: Поле для установки статуса
-        :type password_zen: :class:`django.forms.CharField`
+        :type users: :class:`ModelMultipleChoiceField`
     """
 
     users = forms.ModelMultipleChoiceField(

main/views.py

@@ -27,13 +27,17 @@ from access_controller.settings import ZENDESK_ROLES
 class CustomRegistrationView(RegistrationView):
     """
     Отображение и логика работы страницы регистрации пользователя
+
+    1. Ввод email пользователя, указанный на Zendesk
+    2. В случае если пользователь с данным паролем зарегистрирован на Zendesk и относится к определенной организации, происходит сброс ссылки с установлением пароля на указанный email
+    3. Создается пользователь class User, а также его профиль
     """
     form_class = CustomRegistrationForm
     template_name = 'django_registration/registration_form.html'
     success_url = reverse_lazy('django_registration_complete')
     is_allowed = True
 
-    def register(self, form):
+    def register(self, form: CustomRegistrationForm) -> User:
         self.is_allowed = True
         if check_user_exist(form.data['email']) and get_user_organization(form.data['email']) == 'SYSTEM':
             forms = PasswordResetForm(self.request.POST)
@@ -61,7 +65,7 @@ class CustomRegistrationView(RegistrationView):
         else:
             self.is_allowed = False
 
-    def get_success_url(self, user=None):
+    def get_success_url(self, user: User = None) -> success_url:
         """
         Возвращает url-адрес страницы, куда нужно перейти после успешной/неуспешной регистрации
         Используется самой django-registration
@@ -73,13 +77,9 @@ class CustomRegistrationView(RegistrationView):
 
 
 @login_required()
-def profile_page(request):
+def profile_page(request: UserProfile) -> UserProfile:
     """
     Отображение страницы профиля
-
-    :param request: объект с деталями запроса
-    :type request: :class:`django.http.HttpResponse`
-    :return: объект ответа сервера с HTML-кодом внутри
     """
     user_profile = request.user.userprofile
     update_profile(user_profile)
@@ -95,17 +95,26 @@ def profile_page(request):
 
 
 def main_page(request):
+    """
+        Отображение логгирования на главной странице
+    """
     logger = logging.getLogger('main.index')
     logger.info('Index page opened')
     return render(request, 'pages/index.html')
 
 
 class AdminPageView(FormView, LoginRequiredMixin):
+    """
+        Class AdminPageView - логика работы страницы администратора
+    """
     template_name = 'pages/adm_ruleset.html'
     form_class = AdminPageUsers
     success_url = '/control/'
 
-    def form_valid(self, form):
+    def form_valid(self, form: AdminPageUsers) -> AdminPageUsers:
+        """
+            Функция установки ролей пользователям
+        """
         if 'engineer' in self.request.POST:
             self.make_engineers(form.cleaned_data['users'])
         elif 'light_agent' in self.request.POST:
@@ -121,7 +130,10 @@ class AdminPageView(FormView, LoginRequiredMixin):
         [make_light_agent(user) for user in users]
 
     @staticmethod
-    def count_users(users):  # TODO: this func counts users from all zendesk instead of just from a model
+    def count_users(users: User) -> int: #.. todolist:: :this func counts users from all zendesk instead of just from a model:
+        """
+            Функция подсчета количества сотрудников с ролями engineer и light_a
+        """
         engineers, light_agents = 0, 0
         for user in users:
             if user.custom_role_id == ZENDESK_ROLES['engineer']:
@@ -130,7 +142,10 @@ class AdminPageView(FormView, LoginRequiredMixin):
                 light_agents += 1
         return engineers, light_agents
 
-    def get_context_data(self, **kwargs):
+    def get_context_data(self, **kwargs) -> list:
+        """
+        Функция формирования контента страницы администратора (с проверкой прав доступа)
+        """
         if self.request.user.userprofile.role != 'admin':
             raise PermissionDenied
         context = super().get_context_data(**kwargs)

requirements.txt

@@ -8,4 +8,5 @@ django_registration==3.1.1
 # Documentation
 Sphinx==3.4.3
 sphinx-rtd-theme==0.5.1
+sphinx-autodoc-typehints==1.11.1