Merge branch 'feature/documentation' into 'develop'

Feature/documentation

See merge request 2020-2021/online/s101/group-02/access_controller!27

main/forms.py

@@ -7,10 +7,15 @@ from main.models import UserProfile
 
 class CustomRegistrationForm(RegistrationFormUniqueEmail):
     """
-    Форма для регистрации :class:`django_registration.forms.RegistrationFormUniqueEmail`
-    с добавлением bootstrap-класса 'form-control'
+        Форма для регистрации :class:`django_registration.forms.RegistrationFormUniqueEmail`
+
+        с добавлением bootstrap-класса "form-control"
+
+        :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):
@@ -27,7 +32,10 @@ class CustomRegistrationForm(RegistrationFormUniqueEmail):
 
 class AdminPageUsers(forms.Form):
     """
-        Форма для установки статуса
+        Форма для установки статусов engineer или light_agent пользователям
+
+        :param users: Поле для установки статуса
+        :type users: :class:`ModelMultipleChoiceField`
     """
 
     users = forms.ModelMultipleChoiceField(
@@ -43,8 +51,8 @@ class AdminPageUsers(forms.Form):
 
 class CustomAuthenticationForm(AuthenticationForm):
     """
-    Форма для авторизации :class:`django.contrib.auth.forms.AuthenticationForm`
-    с изменением поля username на email
+        Форма для авторизации :class:`django.contrib.auth.forms.AuthenticationForm`
+        с изменением поля username на email
     """
     username = forms.CharField(
         label="Электронная почта",

main/views.py

@@ -26,13 +26,17 @@ from .models import UserProfile
 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)
@@ -60,7 +64,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
@@ -72,13 +76,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)
@@ -140,17 +140,26 @@ def work_become_engineer(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:
@@ -166,7 +175,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']:
@@ -175,7 +187,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

@@ -9,3 +9,4 @@ django_registration==3.1.1
 Sphinx==3.4.3
 sphinx-rtd-theme==0.5.1
 sphinx-autodoc-typehints==1.11.1
+