Описание технической реализации сайта
======================================

.. raw:: html

   <style>
      .llama-picture {
          margin: 0 0 10px 15px;
          width: 150px;
          height: 180px;
      }
   </style>

.. image:: ../_static/sticker_lama_nothing.jpg
    :scale: 30%
    :align: center
    :class: llama-picture

.. todo::
    Данный раздел описывает техническую сторону создания и развертывания статического сайта на основе инструмента Sphinx с использованием различных расширений для улучшения 
    функциональности и визуализации. Сайт был разработан с учетом современных подходов к созданию документации, что обеспечивает удобство использования как для автора, так и для читателей.

    1. Общая информация
    -------------------

    - **Инструмент генерации**: Sphinx — это мощный инструмент для создания документации и статических сайтов.
    - **Тема**: Furo — современная тема для Sphinx, обеспечивающая адаптивный дизайн и удобную навигацию.
    - **Размещение**: GitHub Pages — бесплатная платформа для публикации статических сайтов.
    - **CI/CD pipeline**: GitHub Actions используется для автоматической сборки и деплоя сайта при каждом обновлении репозитория.

    2. Используемые расширения
    --------------------------

    Ниже приведено описание каждого из используемых расширений:

    2.1 ``sphinxcontrib.plantuml``

    - Описание: Это расширение позволяет создавать UML-диаграммы, блок-схемы и другие визуальные материалы с помощью PlantUML.
    - Применение: В проекте используется для демонстрации архитектурных решений и процессов (например, C4-диаграммы).

    2.2 ``sphinx_tabs.tabs``

    - Описание: Расширение для создания вкладок, которые позволяют показывать различные примеры кода или информацию в компактном виде.
    - Применение: Используется для сравнения примеров кода на разных языках программирования или демонстрации нескольких вариантов решения одной задачи.

    2.3 ``sphinx_design``

    - Описание: Добавляет возможность создания карточек, баннеров и других визуальных элементов для улучшения внешнего вида документации.
    - Применение: Применяется для создания привлекательных секций с информацией (например, блоговые посты или проекты).

    2.4 ``sphinx.ext.githubpages``

    - Описание: Это расширение добавляет поддержку файлов, необходимых для корректной работы GitHub Pages.
    - Применение: Используется для публикации документации на платформе GitHub Pages.

    2.5 ``jupyter_sphinx``

    - Описание: Позволяет внедрять интерактивные блоки кода Jupyter Notebook прямо в документацию.
    - Применение: Используется для демонстрации выполнения кода и его результатов в реальном времени.

    2.6 ``sphinx_tags``

    - Описание: Расширение для добавления тегов и категорий к страницам документации, что упрощает навигацию и поиск информации.
    - Применение: Применяется для организации контента по тематическим группам (например, "API", "Проекты", "Блог").

    2.7 ``sphinxcontrib.mermaid``

    - Описание: Поддерживает создание диаграмм Mermaid внутри Sphinx, что позволяет легко добавлять графические материалы.
    - Применение: Используется для отображения схем процессов, классовых диаграмм и других визуальных элементов.

    2.8 ``sphinx.ext.mathjax``

    - Описание: Обеспечивает поддержку математических формул через MathJax.
    - Применение: Применяется для написания сложных математических выражений в документации.

    2.9 ``sphinx_copybutton``

    - Описание: Добавляет кнопку "Копировать" в блоки кода для удобного использования примеров.
    - Применение: Упрощает работу пользователей с примерами кода, предоставляя возможность быстро скопировать их содержимое.

    2.10 ``sphinx-jsonschema``

    - Описание: Расширение для описания JSON Schema в документации.
    - Применение: Используется для детального описания структуры запросов и ответов API.

    2.11 ``sphinxcontrib.openapi``

    - Описание: Поддерживает спецификацию OpenAPI для описания RESTful API.
    - Применение: Применяется для создания интерактивной документации API с примерами запросов и ответов.

    2.12 ``myst_parser``

    - Описание: Расширение для поддержки Markdown-файлов в Sphinx.
    - Применение: Позволяет использовать .md-файлы наряду с .rst для создания контента.

    2.13 Собственные расширения Sphinx

    2.13.1 ``sphinx.ext.autodoc``

    - Описание: Автоматически генерирует документацию из комментариев в коде (docstrings).
    - Применение: Не используется в данном проекте напрямую, но может быть полезно для будущих расширений.

    2.13.2 ``sphinx.ext.extlinks``

    - Описание: Упрощает создание ссылок на внешние ресурсы.
    - Применение: Может использоваться для добавления ссылок на issues, pull requests или другие внешние источники.

    2.13.3 ``sphinx.ext.intersphinx``

    - Описание: Обеспечивает ссылки на документацию других проектов.
    - Применение: Может быть полезно для интеграции со сторонними библиотеками или сервисами.

    2.13.4 ``sphinx.ext.todo``

    - Описание: Позволяет создавать заметки задач (todos) в документации.
    - Применение: Используется для управления незавершенными частями документации.

    2.13.5 ``sphinx.ext.viewcode``

    - Описание: Добавляет возможность просмотра исходного кода для каждого объекта документации.
    - Применение: Полезно для разработчиков, желающих изучить внутреннюю реализацию.

    3. Структура проекта организована следующим образом
    ----------------------------------------------------

    .. code-block:: 
        
        tech_writer_portfolio/
        ├── source/
        │   ├── index.rst          # Главная страница
        │   ├── projects/          # Раздел "Проекты"
        │   │   ├── index.rst
        │   │   ├── project_1.rst
        │   │   └── project_2.rst
        │   ├── skills/            # Раздел "Навыки"
        │   │   └── index.rst
        │   ├── blog/             # Раздел "Блог"
        │   │   ├── index.rst
        │   │   └── post_1.rst
        │   ├── technical/         # Раздел "Техническая реализация"
        │   │   └── index.rst
        │   ├── resume.rst         # Страница резюме
        │   ├── _static/           # Папка для статических файлов (CSS, JS, изображения)
        │   │   ├── custom.css
        │   │   ├── print_button.js
        │   │   ├── export_pdf.js
        │   │   └── example_api_response.yaml  # Файл OpenAPI спецификации
        │   ├── _templates/        # Папка для шаблонов HTML
        │   └── conf.py            # Конфигурационный файл Sphinx
        ├── build/                 # Директория для выходных файлов
        ├── .github/               # Настройки CI/CD через GitHub Actions
        │   └── workflows/
        │       └── deploy.yml     # Pipeline для деплоя на GitHub Pages
        ├── requirements.txt        # Зависимости проекта
        └── Makefile               # Файл для управления сборкой

    4. Используемые технологии
    ---------------------------

    4.1 Sphinx
    +++++++++++

    Sphinx был выбран как основной инструмент для создания сайта из-за его гибкости и возможности использовать множество расширений для добавления дополнительного функционала. Ключевые особенности:

    - reStructuredText (.rst) позволяет легко создавать структурированный текст.
    - Благодаря плагинам, можно добавлять диаграммы, математические формулы, блоки кода и другие элементы.

    4.2 Тема Furo
    ++++++++++++++

    Furo была выбрана за следующие преимущества:

    - Адаптивный дизайн для различных устройств.
    - Поддержка светлой и темной тем.
    - Встроенная поддержка сворачиваемых меню и других интерактивных элементов.

    4.3 Расширения Sphinx
    ++++++++++++++++++++++

    Для расширения функциональности были использованы следующие расширения:

    - ``sphinx.ext.mathjax``: Для отображения математических формул.
    - ``sphinxcontrib.plantuml``: Для создания UML-диаграмм.
    - ``sphinxcontrib.mermaid``: Для визуализации процессов и архитектурных решений.
    - ``sphinx_togglebutton``: Для создания сворачиваемых блоков.
    - ``sphinx-jsonschema``: Для описания JSON Schema в документации.
    - ``sphinxcontrib.openapi``: Для работы с OpenAPI спецификацией.

    5. Процесс создания
    ---------------------

    5.1 Настройка окружения
    ++++++++++++++++++++++++

    1) **Python**: Установлен Python 3.8+ для работы с Sphinx.
    2) **Виртуальное окружение**: Создано с помощью команды ``python -m venv venv``.
    3) **Зависимости**: Все зависимости указаны в файле ``requirements.txt`` и включают следующие ключевые пакеты:

    .. code-block:: 

        sphinx
        furo
        sphinxcontrib.plantuml
        sphinx_tabs.tabs
        sphinx_design
        sphinx-jsonschema
        sphinxcontrib.openapi
        myst_parser

    5.2 Инициализация проекта
    ++++++++++++++++++++++++++
    Проект был инициализирован с помощью команды ``sphinx-quickstart``. В конфигурационном файле ``conf.py`` были добавлены необходимые расширения и настроена тема Furo:

    .. code-block:: python

        extensions = [
            'sphinxcontrib.plantuml',
            'sphinx_tabs.tabs',
            'sphinx_design',
            'sphinx.ext.githubpages',
            'jupyter_sphinx',
            'sphinx_tags',
            'sphinxcontrib.mermaid',
            'sphinx.ext.mathjax',
            'sphinx_copybutton',    
            'sphinx-jsonschema',
            'sphinxcontrib.openapi',
            'myst_parser',
        ]

        html_theme = 'furo'


    6. Развертывание на GitHub Pages
    ---------------------------------

    6.1 Настройка GitHub Actions
    ++++++++++++++++++++++++++++++

    Для автоматической сборки и развертывания сайта используется GitHub Actions. Содержимое файла ``.github/workflows/deploy.yml``:

    .. code-block:: yaml

        name: Deploy to GitHub Pages

        on:
        push:
            branches:
            - main

        jobs:
        build-and-deploy:
            runs-on: ubuntu-latest
            steps:
            - name: Checkout code
                uses: actions/checkout@v2

            - name: Set up Python
                uses: actions/setup-python@v2
                with:
                python-version: '3.9'

            - name: Install dependencies
                run: |
                pip install -r requirements.txt

            - name: Build Sphinx site
                run: |
                make html

            - name: Deploy to GitHub Pages
                uses: peaceiris/actions-gh-pages@v3
                with:
                github_token: ${{ secrets.GITHUB_TOKEN }}
                publish_dir: ./build/html

    **Как это работает**:

    1) При каждом коммите в ветку ``main`` запускается GitHub Actions workflow.
    2) Workflow устанавливает зависимости, собирает сайт с помощью Sphinx (``make html``) и разворачивает результат в директории ``build/html``.
    3) Содержимое ``build/html`` публикуется на GitHub Pages.

    7. Особенности реализации
    ---------------------------

    7.1 Диаграммы
    ++++++++++++++

    Для создания диаграмм использовались PlantUML и Mermaid:

    - PlantUML: Создание UML-диаграмм (например, C4-диаграммы).
    - Mermaid: Создание графических схем процессов и архитектурных решений.

    Пример использования PlantUML:

    .. code-block:: rst

        .. uml::
            
            @startuml
            Alice -> Bob: Привет
            Bob --> Alice: Привет обратно
            @enduml

    Результат:

    .. plantuml::
        
        @startuml
        Alice -> Bob: Привет
        Bob --> Alice: Привет обратно
        @enduml


    Пример использования Mermaid:

    .. code-block:: rst

        .. mermaid::

            graph TD
                A[Клиент] --> B{API}
                B -->|POST /calculate-heating| C[Сервер]
                C -->|JSON Response| A

    Результат:

    .. mermaid::

        graph TD
            A[Клиент] --> B{API}
            B -->|POST /calculate-heating| C[Сервер]
            C -->|JSON Response| A

    7.2 Резюме
    +++++++++++

    Страница резюме имеет следующие функции:

    - **Распечатка**: Кнопка "Распечатать резюме" вызывает функцию ``window.print()`` для печати текущей страницы.

    .. Готовый PDF: Предоставлена возможность скачать уже подготовленный PDF-файл, сгенерированный через Sphinx (sphinx-build -b latex).

    Пример кнопок на странице резюме:

    .. code-block:: rst

        .. raw:: html

            <button id="print-button" style="background-color: #007bff; color: white; padding: 10px 20px; border: none; border-radius: 5px; cursor: pointer;">
                Распечатать резюме
            </button>

            <script src="../_static/print_button.js"></script>
        

    7.3 API Документация
    +++++++++++++++++++++

    Для документации API использовалось расширение ``sphinxcontrib.openapi``:

    - **OpenAPI спецификация**: Хранится в файле ``example_api_response.yaml`` (или ``.json``).
    - **Подключение спецификации**:

    .. code-block:: rst

        .. openapi:: ../_static/example_api_response.yaml
            :examples:

    - **JSON Schema**: Для отдельных схем запросов/ответов используется расширение ``sphinx-jsonschema``.

    8. Настройка стилей
    --------------------

    8.1 Пользовательские CSS
    +++++++++++++++++++++++++

    Для кастомизации дизайна создан файл custom.css в директории ``_static/``:

    .. code-block:: css
        
        /* Стили для печати */
        @media print {
            .no-print, header, footer, nav, button, a {
                display: none !important;
            }
            body {
                font-family: Arial, sans-serif;
                font-size: 12pt;
                line-height: 1.5;
                margin: 20mm;
            }
        }

        /* Стили для кнопок */
        #export-pdf, #print-button {
            background-color: #007bff;
            color: white;
            padding: 10px 20px;
            border: none;
            border-radius: 5px;
            cursor: pointer;
            margin-right: 10px;
        }

        #export-pdf {
            background-color: #28a745;
        }

    8.2 JavaScript
    ++++++++++++++

    Для добавления интерактивности созданы следующие скрипты:

    - ``print_button.js``: Обеспечивает функционал распечатки страницы.
    
    .. ``export_pdf.js``: Экспортирует содержимое страницы в PDF с помощью jsPDF.

    Пример ``print_button.js``:

    .. code-block:: javascript

        document.addEventListener('DOMContentLoaded', function () {
            const printButton = document.getElementById('print-button');
            printButton.addEventListener('click', function () {
                window.print();
            });
        });

    9. Автоматическая генерация PDF
    --------------------------------

    Для создания готового PDF-файла резюме используется LaTeX через Sphinx:

    1) Настройка в ``conf.py``:

    .. code-block:: python

        latex_documents = [
            ('resume', 'resume.tex', 'Резюме', 'Роман Удальцов', 'manual'),
        ]

    2) Сборка PDF:

    .. code-block:: bash

        sphinx-build -b latex source build/pdf
        cd build/pdf
        pdflatex resume.tex


    3)Скачивание PDF:

    Добавлена ссылка для скачивания готового файла:

    .. code-block:: rst

        :download:`Скачать готовое резюме <../build/pdf/resume.pdf>`


    10. CI/CD Pipeline
    ------------------

    Pipeline для автоматической сборки и развертывания сайта настроен через GitHub Actions:

    1) **Checkout кода**: Код проекта клонируется из репозитория.
    2) **Установка зависимостей**: Устанавливаются все зависимости из ``requirements.txt``.
    3) **Сборка сайта**: Выполняется команда ``make html`` для генерации HTML-файлов.
    4) **Развертывание**: Содержимое директории ``build/html`` публикуется на GitHub Pages

    10. Тестирование и отладка
    --------------------------

    Для тестирования и отладки использовались следующие инструменты:

    - Sphinx warnings/errors: При сборке проекта проверялись предупреждения и ошибки (``make html``).
    - YAML Validator: Для проверки корректности OpenAPI спецификации.
    - Browser Developer Tools: Для анализа внешнего вида и поведения интерактивных элементов.