Merge branch 'feature/documentation' into 'develop'

Feature/documentation

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

docs/source/code.rst

@@ -1,16 +1,34 @@
-*****
-TODOs
-*****
+Документация разработчика
+=========================
 
+
+******
+Models
+******
+
+.. automodule:: main.models
+   :members:
+
+
+******
+Forms
+******
+
+.. automodule:: main.forms
+   :members:
+
+
+***************
 Extra Functions
----------------
+***************
 
 .. automodule:: main.extra_func
    :members:
 
 
+*****
 Views
------
+*****
 
 .. automodule:: main.views
    :members:

docs/source/index.rst

@@ -6,13 +6,14 @@
 Welcome to ZenDesk Access Controller's documentation!
 =====================================================
 
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   code.rst
-   todo.rst
+   overview
+   code
+   todo
+
 
 
 Indices and tables

docs/source/overview.rst

@@ -0,0 +1,18 @@
+
+Документация пользователя
+=========================
+
+**Управление правами доступа**
+
+
+**ZenDesk Access Controller** - Web-приложение, для выдачи прав пользователям системы по запросу самого пользователя.
+
+Например, из 12 человек 3 сейчас работают с правами администратора, по окончании рабочей смены они сдают свои права (освобождают места) и другие пользователи могут запросить эти права в свое пользование.
+
+Оставшиеся 9 человек получают права легкого агента - без прав редактирования, а только чтение.
+
+**Интерфейс пользователя:**
+
+
+
+.. |copy| unicode:: 0xA9 .. Школа программистов S101, группа 2. 2021гю

docs/source/todo.rst

@@ -1,5 +1,11 @@
+Что необходимо доделать?
+=======================
+
+
+
 *****
 TODOs
 *****
 
 .. todolist::
+

main/extra_func.py

@@ -6,9 +6,20 @@ from zenpy.lib.exception import APIException
 from main.models import UserProfile
 
 
-# Дополнительные функции
 class ZendeskAdmin:
-    # Класс существует, чтобы в каждой фунциии отдельно не проверять аккаунт администратора
+    """
+        Класс **ZendeskAdmin** существует, чтобы в каждой фунциии отдельно не проверять аккаунт администратора
+
+        :param credentials:  Полномочия (первым указывается учетная запись организации в Zendesk)
+        :type credentials: :class:`list of dictionaries`
+        :param email: Email администратора, указанный в env
+        :type email: :class:`email`
+        :param token: Токен администратора (формируется в Zendesk, указывается в env)
+        :type token: :class:`str`
+        :param password: Пароль администратора, указанный в env
+        :type password: :class:`str`
+    """
+
     credentials = {
         'subdomain': 'ngenix1612197338'
     }
@@ -20,25 +31,65 @@ class ZendeskAdmin:
         self.create_admin()
 
     def check_user(self, email: str) -> bool:
+        """
+            Функция **check_user** осуществляет проверку существования пользователя в Zendesk
+
+            :param email: Электронная почта пользователя
+            :type email: :class:`email`
+            :return: True, если существует, иначе False
+            :rtype: :class:`bool`
+        """
         return True if self.admin.search(email, type='user') else False
 
     def get_user_name(self, email: str) -> str:
+        """
+            Функция **get_user_name** возвращает имя пользователя
+
+            :param user_name: Имя пользователя
+            :type user_name: :class:`str`
+        """
         user = self.admin.users.search(email).values[0]
         return user.name
 
     def get_user_role(self, email: str) -> str:
+        """
+            Функция **get_user_role** возвращает роль пользователя
+
+            :param user_role: Роль пользователя
+            :type user_role: :class:`str`
+        """
         user = self.admin.users.search(email).values[0]
         return user.role
 
     def get_user_id(self, email: str) -> str:
+        """
+            Функция **get_user_id** возвращает id пользователя
+
+            :param user_id: ID пользователя
+            :type user_id: :class:`str`
+        """
         user = self.admin.users.search(email).values[0]
         return user.id
 
     def get_user_image(self, email: str) -> str:
+        """
+            Функция **get_user_image** возвращает аватар пользователя
+
+            :param user_image: Аватар пользователя
+            :type user_image: :class:`img`
+        """
         user = self.admin.users.search(email).values[0]
         return user.photo['content_url'] if user.photo else None
 
     def create_admin(self) -> None:
+        """
+                Функция **Create_admin()** создает администратора, проверяя наличие вводимых данных в env.
+
+                :param credentials: В список полномочий администратора вносятся email, token, password из env
+                :raise: :class:`ValueError`: исключение, вызываемое если email не введен в env
+                :raise: :class:`APIException`: исключение, вызываемое если пользователя с таким email не существует в Zendesk
+        """
+
         if self.email is None:
             raise ValueError('access_controller email not in env')
         self.credentials['email'] = os.getenv('ACCESS_CONTROLLER_API_EMAIL')
@@ -58,10 +109,10 @@ class ZendeskAdmin:
 
 def update_profile(user_profile: UserProfile):
     """
-    Функция обновляет профиль пользователя в соотвтетствии с текущим в Zendesk
+        Функция обновляет профиль пользователя в соотвтетствии с текущим в Zendesk
 
-    :param user_profile: Объект профиля пользователя
-    :type user_profile: :class:`main.models.UserProfile`
+        :param user_profile: Объект профиля пользователя
+        :type user_profile: :class:`main.models.UserProfile`
     """
     user_profile.name = ZendeskAdmin().get_user_name(user_profile.user.email)
     user_profile.role = ZendeskAdmin().get_user_role(user_profile.user.email)
@@ -90,7 +141,7 @@ def check_user_auth(email: str, password: str) -> bool:
     :param password: Пароль пользователя
     :type password: :class:`str`
     :return: True, если входные данные верны, иначе False
-    :raise :class:`APIException`: исключение, вызываемое если пользователь не аутентифицирован
+    :raise: :class:`APIException`: исключение, вызываемое если пользователь не аутентифицирован
     :rtype: :class:`bool`
     """
     creds = {

main/models.py

@@ -5,6 +5,18 @@ from django.dispatch import receiver
 
 
 class UserProfile(models.Model):
+    """
+           Модель профиля пользователя
+
+           :param user: OneToOneField к модели :class:`django.contrib.auth.models.User`
+           :param role: Код роли пользователя
+           :type role: :class:`integer`
+           :param image: Аватарка
+           :type image: :class:`img`
+           :param name: Имя пользователя на нашем сайте
+           :type name: :class:`str`
+    """
+
     user = models.OneToOneField(to=User, on_delete=models.CASCADE)
     role = models.CharField(default='None', max_length=100)
     image = models.URLField(null=True, blank=True)
@@ -24,18 +36,16 @@ def save_user_profile(sender, instance, **kwargs):
 
 class RoleChangeLogs(models.Model):
     """
-    Модель для логирования изменений ролей пользователя
+        Модель для логирования изменений ролей пользователя
 
-    :param user: Пользователь, которому присвоили другую роль,
-    ForeignKey к модели :class:`django.contrib.auth.models.User`
-    :param name: Имя пользователя
-    :type name: :class:`str`
-    :param new_role: Присвоенная роль
-    :type new_role: :class:`str`
-    :param change_time: Дата изменения роли`
-    :type change_time: :class:`datetime.datetime`
-    :param changed_by: Кем была изменена роль,
-    ForeignKey к модели :class:`django.contrib.auth.models.User`
+        :param user: Пользователь, которому присвоили другую роль,  ForeignKey к модели :class:`django.contrib.auth.models.User`
+        :param name: Имя пользователя
+        :type name: :class:`str`
+        :param new_role: Присвоенная роль
+        :type new_role: :class:`str`
+        :param change_time: Дата изменения роли`
+        :type change_time: :class:`datetime.datetime`
+        :param changed_by: Кем была изменена роль, ForeignKey к модели :class:`django.contrib.auth.models.User`
     """
     user = models.ForeignKey(to=User, on_delete=models.CASCADE)
     name = models.TextField()

requirements.txt

@@ -2,7 +2,7 @@
 Django==3.1.6
 Pillow==8.1.0
 zenpy~=2.0.24
-django-registration==3.1.1
+django_registration==3.1.1
 
 
 # Documentation