diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf..2a4a50c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -14,7 +14,18 @@ help: .PHONY: help Makefile +# Custom targets for documentation management +.PHONY: clean-docs rebuild-docs + +clean-docs: + rm -rf $(BUILDDIR)/ + find $(SOURCEDIR) -name "*.rst" ! -name "index.rst" ! -name "sphinx_guide.rst" -delete + +rebuild-docs: clean-docs + sphinx-apidoc -o $(SOURCEDIR) .. -f + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/build/html/.buildinfo.bak b/docs/build/html/.buildinfo.bak new file mode 100644 index 0000000..4827f51 --- /dev/null +++ b/docs/build/html/.buildinfo.bak @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 56428dc241842362fe772e9fdd966681 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/docs/build/html/.doctrees/components.doctree b/docs/build/html/.doctrees/components.doctree index 0488d33..cd7faff 100644 Binary files a/docs/build/html/.doctrees/components.doctree and b/docs/build/html/.doctrees/components.doctree differ diff --git a/docs/build/html/.doctrees/components_derived.doctree b/docs/build/html/.doctrees/components_derived.doctree index 383dc52..2e21556 100644 Binary files a/docs/build/html/.doctrees/components_derived.doctree and b/docs/build/html/.doctrees/components_derived.doctree differ diff --git a/docs/build/html/.doctrees/environment.pickle b/docs/build/html/.doctrees/environment.pickle index 5baa6b9..0fada94 100644 Binary files a/docs/build/html/.doctrees/environment.pickle and b/docs/build/html/.doctrees/environment.pickle differ diff --git a/docs/build/html/.doctrees/index.doctree b/docs/build/html/.doctrees/index.doctree index c1ad613..640898d 100644 Binary files a/docs/build/html/.doctrees/index.doctree and b/docs/build/html/.doctrees/index.doctree differ diff --git a/docs/build/html/.doctrees/pages.doctree b/docs/build/html/.doctrees/pages.doctree index c034f52..d0a5aaa 100644 Binary files a/docs/build/html/.doctrees/pages.doctree and b/docs/build/html/.doctrees/pages.doctree differ diff --git a/docs/build/html/.doctrees/sphinx_guide.doctree b/docs/build/html/.doctrees/sphinx_guide.doctree new file mode 100644 index 0000000..e10ef52 Binary files /dev/null and b/docs/build/html/.doctrees/sphinx_guide.doctree differ diff --git a/docs/build/html/_modules/components_derived/interactive_dropdown_list.html b/docs/build/html/_modules/components_derived/interactive_dropdown_list.html new file mode 100644 index 0000000..b3f3c7f --- /dev/null +++ b/docs/build/html/_modules/components_derived/interactive_dropdown_list.html @@ -0,0 +1,512 @@ + + + + + + + + components_derived.interactive_dropdown_list — документация e-nms-qa-automation 0.1.0 + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Исходный код components_derived.interactive_dropdown_list

+"""Модуль interactive_dropdown_list_component содержит класс для работы с интерактивными выпадающими списками,
+позволяющими сделать выбор нескольких элементов.
+
+Класс InteractiveDropdownList наследует базовый функционал BaseComponent и добавляет
+методы для взаимодействия с интерактивными выпадающими списками на странице.
+"""
+
+from playwright.sync_api import Page, Locator, expect
+from tools.logger import get_logger
+from components.base_component import BaseComponent
+
+logger = get_logger("INTERACTIVE_DROPDOWN_LIST")
+
+

+[документация]
+class InteractiveDropdownList(BaseComponent):
+    """Класс для работы с выпадающими списками.
+
+    Наследует функциональность BaseElement и добавляет специфичные
+    методы для выбора и проверки элементов списка.
+    """
+
+

+[документация]
+    def __init__(self, page: Page) -> None:
+        """Инициализирует компонент интерактивного выпадающего списка.
+
+        Args:
+           page: Экземпляр страницы Playwright.
+        """
+
+        super().__init__(page)

+
+
+    # Действия:
+

+[документация]
+    def get_checkbox_locator(self, text: str) -> Locator:
+        """Возвращает локатор чек-бокса для элемента списка с указанным текстом.
+
+        Args:
+            text (str): Текст элемента для выбора.
+        """
+
+        checkbox_locator = self.get_locator('div.v-list__tile__title').get_by_text(text). \
+                           locator("../..").locator("//input[@role='checkbox']")
+        expect(checkbox_locator).to_be_visible(), \
+            f"Checkbox for dropdown list item with text {text} is missing"
+        return checkbox_locator

+
+
+

+[документация]
+    def deselect_item_with_text(self, text: str) -> None:
+        """Выбирает элемент списка по указанному тексту.
+
+        Args:
+            text (str): Текст элемента для выбора.
+        """
+
+        self.get_checkbox_locator(text).uncheck(force=True)

+
+
+

+[документация]
+    def select_item_with_text(self, text: str) -> None:
+        """Выбирает элемент списка по указанному тексту.
+
+        Args:
+            text (str): Текст элемента для выбора.
+        """
+        self.get_checkbox_locator(text).check(force=True)

+
+
+

+[документация]
+    def get_selected_items(self, locator: str|Locator) -> list[str]:
+        """Возвращает список отмеченных элементов."""
+
+        selected_items = []
+
+        list_locator = self.get_locator(locator)
+
+        items = list_locator.get_by_role("listitem").all()
+
+        for item in items:
+            if item.get_by_role("checkbox").is_checked():
+                item_text = item.text_content().strip()
+                if item_text:
+                    selected_items.append(item_text)
+
+        return selected_items

+

+
+
+    # Проверки:
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/build/html/_modules/components_derived/settings_form_component.html b/docs/build/html/_modules/components_derived/settings_form_component.html new file mode 100644 index 0000000..30ddd7e --- /dev/null +++ b/docs/build/html/_modules/components_derived/settings_form_component.html @@ -0,0 +1,552 @@ + + + + + + + + components_derived.settings_form_component — документация e-nms-qa-automation 0.1.0 + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Исходный код components_derived.settings_form_component

+"""Модуль компонента формы ввода и отображения полей настроек. Содержит класс для работы с формами ввода
+и отображения полей настроек,их элементами и проверками."""
+
+from playwright.sync_api import Page, Locator
+from tools.logger import get_logger
+from locators.settings_form_locators import SettingsFormLocators
+from elements.tooltip_button_element import TooltipButton
+from elements.button_element import Button
+from components.toolbar_component import ToolbarComponent
+from components.base_component import BaseComponent
+
+logger = get_logger("SETTINGS_FORM")
+
+
+

+[документация]
+class SettingsFormComponent(BaseComponent):
+    """Компонент формы ввода и отображения полей настроек. Предоставляет методы для взаимодействия с формой,
+    ее содержимым и проверок."""
+
+

+[документация]
+    def __init__(self, page: Page):
+        super().__init__(page)
+        self.toolbar = ToolbarComponent(page, "")
+        self.content_items = {}
+        self.buttons = []

+
+
+    # Действия:
+

+[документация]
+    def add_content_item(self, name: str, item: object) -> None:
+        """Добавляет элемент содержимого в форму по заданному имени."""
+
+        self.content_items[name] = item

+
+
+

+[документация]
+    def get_content_item(self, name: str) -> object | None:
+        """Возвращает элемент содержимого по имени или None, если не найден."""
+
+        return self.content_items.get(name)

+
+
+

+[документация]
+    def add_toolbar_title(self, title: str) -> None:
+        """Добавляет заголовок в панель инструментов модального окна."""
+
+        self.toolbar.add_title(title)

+
+
+

+[документация]
+    def add_button(self, locator: str, name: str) -> None:
+        """Добавляет кнопку в форму."""
+
+        self.buttons.append(Button(self.page, locator, name))

+
+
+

+[документация]
+    def add_tooltip_button(self, locator: str, name: str) -> None:
+        """Добавляет кнопку в форму."""
+
+        self.buttons.append(TooltipButton(self.page, locator, name))

+
+
+

+[документация]
+    def get_button_by_name(self, name: str) -> Button | TooltipButton | None:
+        """Ищет и возвращает кнопку по имени или None, если не найдена."""
+
+        for button in self.buttons:
+            if button.name == name:
+                return button
+        return None

+
+
+

+[документация]
+    def click_button(self, name: str) -> None:
+        """Кликает по кнопке с заданным именем. Вызывает ошибку, если не найдена."""
+
+        button = self.get_button_by_name(name)
+        if button is None:
+            assert False, f"Button with name '{name}' not found"
+        button.click()

+
+
+    # Проверки:
+

+[документация]
+    def check_vertical_scrolling(self, locator: str| Locator) -> bool:
+        """Проверяет возможность вертикальной прокрутки формы."""
+
+        return self.is_scrollable_vertically(locator)

+
+
+

+[документация]
+    def check_button_tooltip(self, name: str, tooltip: str) -> None:
+        """Проверяет текст подсказки кнопки. """
+
+        button = self.get_button_by_name(name)
+        if button is None:
+            raise AssertionError(f"Unsupported button name {name}")
+        button.check_tooltip_with_text(tooltip)

+
+
+

+[документация]
+    def check_button_visibility(self, name: str) -> None:
+        """Проверяет наличие кнопки по имени. Вызывает ошибку, если не найдена."""
+
+        button = self.get_button_by_name(name)
+        if button is None:
+            assert False, f"Button with name '{name}' not found"
+        button.check_visibility(f"Button with name '{name}' is missing")

+
+
+

+[документация]
+    def should_be_toolbar(self) -> None:
+        """Проверяет наличие тулбара.
+
+        Raises:
+            AssertionError: Если тулбар или кнопка редактирования отсутствуют.
+        """
+
+        self.toolbar.check_toolbar_presence_by_locator_and_title(SettingsFormLocators.SETTTINGS_FORM_SCROLL_CONTAINER,
+                                                                 "Session settings form toolbar is missing")

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/build/html/_modules/index.html b/docs/build/html/_modules/index.html index 2b6c811..f4b921e 100644 --- a/docs/build/html/_modules/index.html +++ b/docs/build/html/_modules/index.html @@ -89,10 +89,6 @@
  • NavigationPanelComponent
    • -
  • components.settings_form_component module -
  • components.table_component module @@ -114,6 +110,10 @@
  • DateInput
    • +
  • components_derived.interactive_dropdown_list module +
  • components_derived.modal_add_AD_user module @@ -142,6 +142,10 @@
  • SelectionBarComponent
    • +
  • components_derived.settings_form_component module +
  • components_derived.sidebar_filter_component module @@ -238,10 +242,6 @@
  • LicenseTab
    • -
  • pages.location_page module -
  • pages.login_page module @@ -250,6 +250,10 @@
  • MainPage
    • +
  • pages.push_notifications_settings_tab module +
  • pages.service_status_tab module @@ -292,6 +296,60 @@
    • + +

    Документация и руководства:

    + @@ -329,11 +387,11 @@
  • components.json_container_component
  • components.modal_window_component
  • components.navbar_component
    • -
  • components.settings_form_component
  • components.table_component
  • components.toolbar_component
  • components_derived.container_system_log_events
  • components_derived.date_input_component
    • +
  • components_derived.interactive_dropdown_list
  • components_derived.modal_add_AD_user
  • components_derived.modal_add_local_user
  • components_derived.modal_change_password
    • @@ -341,6 +399,7 @@
  • components_derived.modal_view_template
  • components_derived.modal_view_ztp_template
  • components_derived.selection_bar_component
    • +
  • components_derived.settings_form_component
  • components_derived.sidebar_filter_component
  • components_derived.user_card
  • conftest
    • @@ -358,9 +417,9 @@
  • pages.base_page
  • pages.current_session_tab
  • pages.license_tab
    • -
  • pages.location_page
  • pages.login_page
  • pages.main_page
    • +
  • pages.push_notifications_settings_tab
  • pages.service_status_tab
  • pages.session_settings_tab
  • pages.templates_tab
    • diff --git a/docs/build/html/_modules/pages/push_notifications_settings_tab.html b/docs/build/html/_modules/pages/push_notifications_settings_tab.html new file mode 100644 index 0000000..05ac1e4 --- /dev/null +++ b/docs/build/html/_modules/pages/push_notifications_settings_tab.html @@ -0,0 +1,650 @@ + + + + + + + + pages.push_notifications_settings_tab — документация e-nms-qa-automation 0.1.0 + + + + + + + + + + + + + + + + +
    + + +
    + +
    +
    +
    + +
    +
    +
    +
    + +

    Исходный код pages.push_notifications_settings_tab

    +"""Модуль вкладки настройки Push уведомлений.
+
+Содержит класс PushNotificationsSettings для работы с вкладкой настройки Push уведомлений.
+Позволяет проверять состояние и взаимодействовать с элементами вкладки.
+"""
+
+import re
+from playwright.sync_api import Page
+from locators.settings_form_locators import SettingsFormLocators
+from elements.text_input_element import TextInput
+from elements.text_element import Text
+from components.toolbar_component import ToolbarComponent
+from components.alert_component import AlertComponent
+from components_derived.settings_form_component import SettingsFormComponent
+from components_derived.interactive_dropdown_list import InteractiveDropdownList
+from pages.base_page import BasePage
+
+
+
    
+[документация]
+class PushNotificationsSettingsTab(BasePage):
+    """Класс для работы с вкладкой настройки Push уведомлений.
+
+    Предоставляет методы для взаимодействия с вкладкой настройки Push уведомлений.
+
+    Args:
+        page: Экземпляр страницы Playwright.
+    """
+
+
    
+[документация]
+    def __init__(self, page: Page) -> None:
+        """Инициализирует компоненты вкладки настройки Push уведомлений."""
+
+        super().__init__(page)
+
+
+        self.toolbar = ToolbarComponent(page, "Push уведомления")
+
+        # Форма для отображения/редактирования полей настроек Push уведомлений
+        self.settings_form = SettingsFormComponent(page)
+        self.settings_form.add_toolbar_title("Общие")
+
+        message_setting_label = Text(page,
+                                   page.locator(SettingsFormLocators.SETTTINGS_FORM_SCROLL_CONTAINER).\
+                                   get_by_text('Сообщение'),
+                                   "message_setting_label")
+        self.settings_form.add_content_item("message_setting_label", message_setting_label)
+
+        loc_message_input = page.locator(SettingsFormLocators.SETTTINGS_FORM_SCROLL_CONTAINER).\
+                            get_by_label('Сообщение').nth(1)
+        message_setting_input = TextInput(page, loc_message_input, "message_setting_input")
+        self.settings_form.add_content_item("message_setting_input", message_setting_input)
+
+        users_settings_locator = page.locator(SettingsFormLocators.SETTTINGS_FORM_SCROLL_CONTAINER).\
+                                 get_by_label('Пользователи')
+        users_setting_label = Text(page, users_settings_locator, "users_setting_label")
+        self.settings_form.add_content_item("users_setting_label", users_setting_label)
+
+        users_setting_input = TextInput(page,
+                                        page.locator(SettingsFormLocators.SETTTINGS_FORM_SCROLL_CONTAINER).\
+                                        get_by_role("combobox"),
+                                        "users_setting_input")
+        self.settings_form.add_content_item("users_setting_input", users_setting_input)
+        self.settings_form.add_content_item("users_list", InteractiveDropdownList(page))
+
+        self.settings_form.add_tooltip_button(page.locator(SettingsFormLocators.SETTTINGS_FORM_SCROLL_CONTAINER).\
+                                              get_by_role("button", name='Отправить'),
+                                              "submit_button")
+
+        self.alert = AlertComponent(page)
    
+
+
+    # Действия:
+
    
+[документация]
+    def clear_users_setting_value(self) -> None:
+        """Очищает текущее значение поля настроек 'Пользователи'."""
+
+        selected_users = self.get_users_setting_value()
+        if len(selected_users) > 0:
+            clear_selection_button = self.page.locator(SettingsFormLocators.SETTTINGS_FORM_SCROLL_CONTAINER).\
+                                       get_by_role("combobox").locator(SettingsFormLocators.CLEAR_SELECTION_BUTTON)
+            clear_selection_button.click()
    
+
+
+
    
+[документация]
+    def click_submit_button(self) -> None:
+        """Нажатие кнопки 'Отправить' в форме ввода настроек."""
+
+        self.settings_form.check_button_visibility("submit_button")
+        self.settings_form.get_button_by_name("submit_button").click()
    
+
+
+
    
+[документация]
+    def get_message_setting_value(self) -> str:
+        """Возвращает текущее значение поля настроек 'Сообщение'.
+
+        Returns:
+           str : Текущее значение поля настроек 'Сообщение'.
+        """
+
+        input_field = self.settings_form.get_content_item("message_setting_input")
+        return input_field.get_input_value().strip()
    
+
+
+
    
+[документация]
+    def get_users_setting_value(self) -> str:
+        """Возвращает текущее значение поля настроек 'Пользователи'.
+
+        Returns:
+           str : Текущее значение поля настроек 'Пользователи'.
+        """
+
+        users_setting_field_loc = self.page.locator(SettingsFormLocators.SETTTINGS_FORM_SCROLL_CONTAINER).\
+                                   get_by_role("combobox").locator(SettingsFormLocators.SELECTED_VALUES)
+
+        return users_setting_field_loc.text_content().strip()
    
+
+
+
    
+[документация]
+    def input_message(self, text: str) -> None:
+        """Заполнение поля 'Сообщение'."""
+
+        message_input = self.settings_form.get_content_item("message_setting_input")
+        message_input.clear()
+        message_input.input_value(text)
    
+
+
+
    
+[документация]
+    def deselect_users(self, users: list[str]) -> None:
+        """Изменение значения поля 'Пользователи' путем отмены выбора из выпадающего списка заданных имен."""
+
+        assert len(users) != 0, "Users list should not be empty"
+
+        self.settings_form.get_content_item("users_setting_input").click()
+        users_list = self.settings_form.get_content_item("users_list")
+
+        for user in users:
+            users_list.deselect_item_with_text(user)
+
+        # Закрываем выпадающий список (кликаем вне его)
+        self.page.mouse.click(10, 10)
    
+
+
+
    
+[документация]
+    def select_users(self, users: list[str]) -> None:
+        """Заполнение поля 'Пользователи' путем выбора из выпадающего списка заданных имен."""
+
+        assert len(users) != 0, "Users list should not be empty"
+
+        self.settings_form.get_content_item("users_setting_input").click()
+        users_list = self.settings_form.get_content_item("users_list")
+
+        for user in users:
+            users_list.select_item_with_text(user)
+
+        # Закрываем выпадающий список (кликаем вне его)
+        self.page.mouse.click(10, 10)
    
+
+
+    # Проверки:
+
    
+[документация]
+    def check_content(self):
+        """Проверяет наличие и корректность всех элементов страницы."""
+
+        self.should_be_toolbar()
+
+        self.should_be_form_toolbar()
+
+        for name in self.settings_form.content_items.keys():
+            if name == "users_list":
+                self.settings_form.get_content_item("users_setting_input").click()
+                users_list = self.settings_form.get_content_item(name)
+                selected_users = users_list.get_selected_items(SettingsFormLocators.DROPDOWN_LIST)
+                assert len(selected_users) == 0, "There should be no selected users"
+            else:
+                item = self.settings_form.get_content_item(name)
+                item.check_visibility(
+                    f"Push notifications settings input form item with name '{name}' is missing"
+                )
+
+        self.settings_form.check_button_visibility("submit_button")
+        self.settings_form.check_button_tooltip("submit_button", "Отправить Push уведомление")
    
+
+
+
    
+[документация]
+    def should_be_toolbar(self) -> None:
+        """Проверяет наличие тулбара страницы.
+
+        Raises:
+            AssertionError: Если тулбар или кнопка редактирования отсутствуют.
+        """
+        loc = self.page.get_by_role("navigation").filter(
+              has_text=re.compile("Push уведомления")).locator("div").nth(1)
+        self.toolbar.check_toolbar_presence_by_locator(loc, "Toolbar with title 'Push уведомления' is missing")
    
+
+
+
    
+[документация]
+    def should_be_form_toolbar(self) -> None:
+        """Проверяет наличие тулбара формы редактирования настроек.
+
+        Raises:
+            AssertionError: Если тулбар отсутствует.
+        """
+
+        self.settings_form.should_be_toolbar()
    
+
+
+
    
+[документация]
+    def should_be_success_alert(self) -> None:
+        """Проверяет наличие сообщения об успешной отправке push-уведомления.
+
+        Raises:
+            AssertionError: Если тулбар отсутствует.
+        """
+
+        alert_type = self.alert.get_alert_type()
+        assert alert_type == "success", f"Expected success alert, but got {alert_type} alert"
+
+        self.alert.check_alert_presence('\nPush-уведомление\nуспешно отправлено\n')
+        self.alert.check_alert_absence('\nPush-уведомление\nуспешно отправлено\n')
    
+
    
+
+
    + +
    +
    + +
    +
    +
    +
    + + + + \ No newline at end of file diff --git a/docs/build/html/_modules/pages/session_settings_tab.html b/docs/build/html/_modules/pages/session_settings_tab.html index 91ebe53..e79b664 100644 --- a/docs/build/html/_modules/pages/session_settings_tab.html +++ b/docs/build/html/_modules/pages/session_settings_tab.html @@ -40,8 +40,315 @@ @@ -78,8 +385,8 @@ from elements.text_input_element import TextInput from elements.text_element import Text from components.toolbar_component import ToolbarComponent -from components.settings_form_component import SettingsFormComponent from components.alert_component import AlertComponent +from components_derived.settings_form_component import SettingsFormComponent from pages.base_page import BasePage diff --git a/docs/build/html/_sources/components.rst.txt b/docs/build/html/_sources/components.rst.txt index 97203ac..53f29c5 100644 --- a/docs/build/html/_sources/components.rst.txt +++ b/docs/build/html/_sources/components.rst.txt @@ -92,14 +92,6 @@ components.navbar\_component module :show-inheritance: :undoc-members: -components.settings\_form\_component module -------------------------------------------- - -.. automodule:: components.settings_form_component - :members: - :show-inheritance: - :undoc-members: - components.table\_component module ---------------------------------- diff --git a/docs/build/html/_sources/components_derived.rst.txt b/docs/build/html/_sources/components_derived.rst.txt index 5b58df9..63d7168 100644 --- a/docs/build/html/_sources/components_derived.rst.txt +++ b/docs/build/html/_sources/components_derived.rst.txt @@ -20,6 +20,14 @@ components\_derived.date\_input\_component module :show-inheritance: :undoc-members: +components\_derived.interactive\_dropdown\_list module +------------------------------------------------------ + +.. automodule:: components_derived.interactive_dropdown_list + :members: + :show-inheritance: + :undoc-members: + components\_derived.modal\_add\_AD\_user module ----------------------------------------------- @@ -76,6 +84,14 @@ components\_derived.selection\_bar\_component module :show-inheritance: :undoc-members: +components\_derived.settings\_form\_component module +---------------------------------------------------- + +.. automodule:: components_derived.settings_form_component + :members: + :show-inheritance: + :undoc-members: + components\_derived.sidebar\_filter\_component module ----------------------------------------------------- diff --git a/docs/build/html/_sources/index.rst.txt b/docs/build/html/_sources/index.rst.txt index 772c35a..1a1c46c 100644 --- a/docs/build/html/_sources/index.rst.txt +++ b/docs/build/html/_sources/index.rst.txt @@ -27,6 +27,24 @@ * **Фикстуры (Fixtures)** - подготовка данных * **Утилиты (Tools)** - вспомогательные функции +Инструкции и процессы +--------------------- + +.. toctree:: + :maxdepth: 2 + :caption: Документация и руководства: + + sphinx_guide + +Быстрый старт +------------- + +Для начала работы с проектом: + +1. Установите зависимости: ``pip install -e .`` +2. Запустите тесты: ``pytest tests/`` +3. Соберите документацию: ``sphinx-build docs/source docs/build`` + Индексы и поиск ================ diff --git a/docs/build/html/_sources/pages.rst.txt b/docs/build/html/_sources/pages.rst.txt index 42150fb..2d0ae68 100644 --- a/docs/build/html/_sources/pages.rst.txt +++ b/docs/build/html/_sources/pages.rst.txt @@ -28,14 +28,6 @@ pages.license\_tab module :show-inheritance: :undoc-members: -pages.location\_page module ---------------------------- - -.. automodule:: pages.location_page - :members: - :show-inheritance: - :undoc-members: - pages.login\_page module ------------------------ @@ -52,6 +44,14 @@ pages.main\_page module :show-inheritance: :undoc-members: +pages.push\_notifications\_settings\_tab module +----------------------------------------------- + +.. automodule:: pages.push_notifications_settings_tab + :members: + :show-inheritance: + :undoc-members: + pages.service\_status\_tab module --------------------------------- diff --git a/docs/build/html/_sources/sphinx_guide.rst.txt b/docs/build/html/_sources/sphinx_guide.rst.txt new file mode 100644 index 0000000..06e78ea --- /dev/null +++ b/docs/build/html/_sources/sphinx_guide.rst.txt @@ -0,0 +1,378 @@ +Руководство по документации тестов с помощью Sphinx +==================================================== + +**Версия документа:** 1.0 +**Дата последнего обновления:** 2025-11-27 + +.. contents:: Содержание + :depth: 3 + :local: + +1 Расположение документа +------------------------- + +Данное руководство расположено в структуре проекта по пути: + +.. code-block:: text + + project_root/ + ├── docs/ + │ ├── source/ + │ │ ├── conf.py + │ │ ├── index.rst + │ │ ├── sphinx_guide.rst <-- Этот файл + │ │ └── modules.rst + │ └── build/ + ├── src/ + │ └── your_package/ + └── pyproject.toml + +2 Первичная настройка для нового проекта +----------------------------------------- + +2.1 Подготовка зависимостей +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + # Установка Sphinx и тем + pip install sphinx sphinx-rtd-theme myst-parser + + # Добавление в pyproject.toml + echo [project.optional-dependencies] >> pyproject.toml + echo docs = [ >> pyproject.toml + echo "sphinx>=8.2.3", >> pyproject.toml + echo "sphinx-rtd-theme>=2.0.0", >> pyproject.toml + echo "myst-parser>=2.0.0" >> pyproject.toml + echo ] >> pyproject.toml + +2.2 Инициализация Sphinx +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + # Создание структуры документации + sphinx-quickstart docs --sep -p "PROJECT_NAME" -a "TEAM_NAME" -l ru --ext-autodoc --ext-viewcode --makefile --no-batchfile + +2.3 Настройка конфигурации +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Обновите ``docs/source/conf.py``: + +.. code-block:: python + + import os + import sys + sys.path.insert(0, os.path.abspath('../..')) + + extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', + 'sphinx_rtd_theme', + ] + + autodoc_default_options = { + 'members': True, + 'member-order': 'bysource', + 'special-members': '__init__', + 'undoc-members': True, + 'exclude-members': '__weakref__' + } + + autodoc_typehints = 'description' + napoleon_google_docstring = True + napoleon_numpy_docstring = False + html_theme = 'sphinx_rtd_theme' + +2.4 Настройка главной страницы +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Обновите ``docs/source/index.rst``: + +.. code-block:: rst + + Документация проекта + ==================== + + .. toctree:: + :maxdepth: 3 + :caption: Содержание: + + modules + + Инструкции и процессы + --------------------- + + .. toctree:: + :maxdepth: 2 + :caption: Документация и руководства: + + sphinx_guide + + Описание + ----------- + Основная документация проекта. + + Индексы + ======= + + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` + +3 Работа с существующим проектом +--------------------------------- + +**Примечание:** Для работы с существующим проектом требуется установка Sphinx на локальной машине. + +3.1 Установка зависимостей +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + # Установка Sphinx и необходимых расширений + pip install sphinx sphinx-rtd-theme myst-parser + + # Или установка из зависимостей проекта (если настроено в pyproject.toml) + pip install -e ".[docs]" + +3.2 Генерация документации +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +3.2.1 Базовая генерация +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Генерация .rst файлов из структуры проекта + sphinx-apidoc -o docs/source . -f + + # Сборка HTML документации + sphinx-build -b html docs/source docs/build/html + +3.2.2 Генерация с исключениями +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Исключение определенных папок из документации + sphinx-apidoc -o docs/source . -f --exclude tests/ --exclude migrations/ + +3.2.3 Принудительная перегенерация +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Принудительная перезапись существующих файлов + sphinx-apidoc -o docs/source . -f --force + +3.3 Очистка документации +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Когда требуется очистка: + +- **После удаления модулей** - чтобы убрать ссылки на несуществующие файлы +- **После переименования пакетов** - для актуализации структуры +- **При изменении архитектуры проекта** - для отражения новых модулей +- **При появлении предупреждений** о несуществующих модулях + +3.3.1 Команды очистки +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Удаление старых сгенерированных .rst файлов кроме основных + rm docs/source/modules.rst + rm docs/source/pages.rst + rm docs/source/components.rst + + # Удаление всех .rst файлов кроме основных (Linux/Mac) + find docs/source -name "*.rst" ! -name "index.rst" ! -name "sphinx_guide.rst" -delete + + # Удаление всех .rst файлов кроме основных (Windows PowerShell) + Get-ChildItem docs/source -Filter "*.rst" | Where-Object { $_.Name -notin @("index.rst", "sphinx_guide.rst") } | Remove-Item + +3.3.2 Автоматизация очистки +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: makefile + + .PHONY: clean-docs rebuild-docs + + clean-docs: + rm -rf docs/build/ + find docs/source -name "*.rst" ! -name "index.rst" ! -name "sphinx_guide.rst" -delete + + rebuild-docs: clean-docs + sphinx-apidoc -o docs/source . -f + sphinx-build -b html docs/source docs/build/html + +3.4 Сборка и деплой +~~~~~~~~~~~~~~~~~~~~ + +3.4.1 Локальная сборка +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Базовая сборка HTML + sphinx-build -b html docs/source docs/build/html + + # Сборка с автоматическим обновлением + sphinx-autobuild docs/source docs/build/html + +3.4.2 Проверка качества +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Проверка ссылок + sphinx-build -b linkcheck docs/source docs/build/linkcheck + + # Проверка орфографии (требуется установка sphinxcontrib-spelling) + sphinx-build -b spelling docs/source docs/build/spelling + +3.4.3 Сборка для публикации +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Сборка PDF (требуется LaTeX) + sphinx-build -b latex docs/source docs/build/latex + + # Сборка EPUB + sphinx-build -b epub docs/source docs/build/epub + +3.4.4 Настройка для CI/CD +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Игнорирование билд-папки в Git + echo "docs/_build/html/" >> .gitignore + echo "docs/_build/latex/" >> .gitignore + +4 Конвертация контента из MkDocs в Sphinx +------------------------------------------ + +4.1 Текст +~~~~~~~~~~ + +**MkDocs (markdown):** + +.. code-block:: markdown + + # Заголовок + Текст с **жирным** шрифтом. + - Элемент списка 1 + - Элемент списка 2 + +**Sphinx (reStructuredText):** + +.. code-block:: rst + + Заголовок + ========= + Текст с **жирным** шрифтом. + * Элемент списка 1 + * Элемент списка 2 + +4.2 Таблицы +~~~~~~~~~~~~ + +**MkDocs:** + +.. code-block:: markdown + + | Заголовок 1 | Заголовок 2 | + |-------------|-------------| + | Данные 1 | Данные 2 | + +**Sphinx:** + +.. code-block:: rst + + +-------------+-------------+ + | Заголовок 1 | Заголовок 2 | + +=============+=============+ + | Данные 1 | Данные 2 | + +-------------+-------------+ + +5 Особенности Sphinx +--------------------- + +5.1 Поддержка docstrings +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + def my_function(param1: str, param2: int) -> bool: + """ + Краткое описание функции. + + Args: + param1: Описание параметра 1 + param2: Описание параметра 2 + + Returns: + bool: Описание возвращаемого значения + + Example: + >>> my_function("test", 5) + True + """ + return True + +5.2 Кастомные директивы +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rst + + .. note:: + Это важное примечание. + + .. warning:: + Это предупреждение. + + .. code-block:: python + + def example(): + print("Hello Sphinx!") + +6 Решение проблем +------------------ + +6.1 Проблема: Модули не находятся +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Решение:** Проверьте ``sys.path`` в ``conf.py`` + +6.2 Проблема: Не генерируются docstrings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Решение:** Убедитесь, что установлены расширения ``autodoc`` и ``napoleon`` + +6.3 Проблема: Тема не применяется +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Решение:** Проверьте ``html_theme`` в ``conf.py`` + +7 Дополнительные возможности +----------------------------- + +- **Autosummary** - автоматические summary таблицы +- **Intersphinx** - ссылки между проектами +- **Custom domains** - домены для специфичной документации + +.. _version-history: + +История версий +-------------- + ++---------+------------+-----------------------------------+ +| Версия | Дата | Изменения | ++=========+============+===================================+ +| 1.0 | 2025-11-27 | Первоначальная версия руководства | ++---------+------------+-----------------------------------+ \ No newline at end of file diff --git a/docs/build/html/components.html b/docs/build/html/components.html index d5d13d9..4ec813f 100644 --- a/docs/build/html/components.html +++ b/docs/build/html/components.html @@ -19,7 +19,9 @@ - + + + @@ -41,275 +43,318 @@ @@ -324,6 +369,7 @@
    -