# -*- coding: utf-8 -*-
# ---
# jupyter:
#   jupytext:
#     formats: ipynb,py:light
#     text_representation:
#       extension: .py
#       format_name: light
#       format_version: '1.4'
#       jupytext_version: 1.2.4
#   kernelspec:
#     display_name: Python 3
#     language: python
#     name: python3
# ---

# # Структура HTML референса

# Здесь мысли про то, как устроен 
#
# * референс
# * курсы
# * как ссылаться друг на друга и т.п.
#

# Корень всего SPARK - здесь все про спарк (потенциально, на разных языках программирования)
#
# Пока это только про "ядерный спарк" (core) - т.е. не про стриминг и не про ML 
#
# * dataframe: API
#   * dataframe: датафреймы, строки и столбцы
#   * transform: трансформации
#   * action: 
#   * aggr_group:аггрегации и группировка
#   * sort: сортировка
#   * join:
#   * union:
# * io:
# * rdd:
# * functions: функции
# * data_types: типы данных
#
# Все страницы референса попадают в эту структуру. В референсе описываем только методы и функции. Все остальные описания пока оставляем где-то в стороне.
#
# Структура юпитера и HTML совпадают - создаем мы структуру юпитера, она автоматом собирается в структуру HTML.
#
# Пока не хочу заморачиваться сфинксом - он не позволяет нормально форматировать. Понадеюсь на родной генератор HTML (nbconvert) и на могущество стилей (и bootstrap любимый).
#
# Попробуем создать первую версию референса.

# Есть еще курсы (или уровни) - они представляют из себя
#
# * описательный материал (который можно читать и слушать)
#   * эти материалы связываются в последовательность, что и есть курс
# * сводки ссылок на референс, который позволяет иметь "сжатый" взгляд на референс
#
# Пока непонятна связь курса и сводок - поймем по ходу пьесы.

# ## Сборка референса примитивная

# Как будем собирать референс - просто формируя файлы (питона) и напуская на них юпитекст (формирующий юпитеры), а потом - nbconvert (для формирования HTML)
#
# Пока (!) все делаем в книжках (и связанных с ними файлах), потом - когда устоится и если будет нужно - сделаем приложеньку (или закажем).
#
# Принимаем соглашения о разметке (см. ниже).
#
# Как быть со структурой юпитера:
#
# * в одной книжке держим референс только по одному элементу (функции)
# * в книжке может быть ровно одна маркдаун ячейка с тэгом "what":"docstr" - это ячейка содержит сконвертированный текст докстринга из документации по спарку (для этой функции), пока непонятно, как это будет работать - потом разберемся 
# * задачки помечаем тэгом "what":"tasks" (пока помещаем его в первый элемент - считаем, что до конца юпитера идут задачки)
# * общие задачи держим отдельно (придумаем - как их метить, чтобы они "собирались" в книжку по элементу)
# * есть еще ячейки, помеченные тэгами "what": "setup"/"teardown" - их нужно убирать при генерации HTML-а (они пока вручную вставляются во все книжки, потом будем их вставлять автоматом)

# По текущему соглашению о разметке нужно метить только начало задачек, а также убрать общие задачи из книжек совсем.
#
# Пока пишем на английском языке - перевод на русский будет потом, не будем пока засорять себе мозг русскими и английскими вариантами.

# ## Соглашения о разметке ячеек

# **Используем light формат юпитекста**
#
# **Исходниками считаем light питоны**
#
# То есть мы работать можем где угодно - в юпитере или в редакторе, но сохраняем и версионируем питоны. Попробуем воспользоваться правилом - "не уходить домой не закоммитив исходники" (в гит).
#
# Далее попробуем реализовать правило автотестирования - чтобы из закоммиченного собиралась нормальная версия.
#
# **Для разметки используем метаданные ячейки**
#
# Общий элемент начинается тэгом spe, внутри него идет наша разметка, например:
#
# `{
#     "spe": {
#         "lang": "ru",
#         "what": "tasks"
#      }
# }`
#
# Не стоит бояться переносов - юпитер сам сделает JSON красивым в ячейке, а юпитекст все вытянет в одну строку
#
# **Размечаем пока только маркдаун ячейки**
#
# Исключение - setup и teardown для кода... Подумать...
#
# **Неразмеченные маркдаун ячейки считаем английскими и обычными**
#
# Языковая разметка всегда используется во вторую очередь, сначала происходит разбор юпитера на блоки, а потом уже внутри блоков происходит языковая обработка.
#
# Например, тэгом tasks помечается заголовок на английском (это - единственный тэг). После него в юпитере идет ячейка с этим же заголовком на русском - в ней уже нет тэга tasks: мы сначала "отрезали" задачи, а потом - если есть задача формирования блока задач на каком-то языке - собираем в пределах этого блока ячейки на нужном языке.

# ## Какие программы надо будет создать

# Для создания первой версии референса нам потребуется
#
# * pyl2nb: собирает юпитеры из наших лайт питонов
# * nb2html: второй шаг - конвертирование юпитера в HTML нашего формата (вроде бы такое возможно - см. https://nbconvert.readthedocs.io/en/latest/external_exporters.html) 
# * docstr2md: преобразует doc string из документации spark в наш маркдаун (и как-то апдейтит соответствующий питон)
#
# Вроде все!
