Julia. Литературное программирование

Julia. Литературное программирование.

1 Реализации

1.1 Literate.jl

• Репозиторий: https://github.com/fredrikekre/Literate.jl
• Документация: https://fredrikekre.github.io/Literate.jl
• Позволяет генерировать Markdown-документы, Jupyter-ноутбуки и чистые скрипты из одного исходного файла с комментариями.
• Интегрируется с Documenter.jl для автоматизации документации пакетов.
• Поддерживает выполнение кода и вставку результатов.

1.2 Weave.jl

• Репозиторий: https://github.com/JunoLab/Weave.jl
• Документация: https://weavejl.mpastell.com
• Генерирует научные отчёты в форматах LaTeX, HTML, Jupyter и других.
• Выполняет код, встраивает результаты (текст, графики) в документ.
• Поддерживает синтаксис Noweb и Markdown.

1.3 Documenter.jl

• Репозиторий: https://github.com/JuliaDocs/Documenter.jl
• Документация: https://documenter.juliadocs.org

1.3.1 Documenter.jl + Entangled

• Связка для создания документации с поддержкой перекрёстных ссылок между блоками кода.
• Entangled синхронизирует Markdown-файлы с исходным кодом, а Documenter.jl генерирует финальную документацию.
• Подходит для сложных проектов.

1.4 Entangled

• Репозиторий: https://entangled.github.io/
• Инструмент для отслеживания изменений в Markdown-файлах и автоматической генерации кода.
• Поддерживает систему ссылок между блоками.
• Работает с Pandoc и Documenter.jl.
• Ресурсы:
  • https://forem.julialang.org/jhidding/literate-programming-using-documenterjl-and-entangled-3fmb

1.5 Jupyter Notebook/IJulia

• Классический подход с интерактивными блокнотами, где код сочетается с Markdown-описаниями.
• Позволяет визуализировать результаты вычислений.
• Неудобен для автоматизации.

1.6 Сравнение

• Literate.jl и Weave.jl фокусируются на преобразовании кода в документы с результатами.
• Documenter.jl + Entangled подходит для проектов, где важна синхронизация кода и документации.
• Jupyter идеален для интерактивных исследований, но требует ручного управления.
• Literate.jl проста в интеграции с другими средствами.

2 Связка Julia + Quarto

2.1 Literate.jl + QuartoFlavor

• Используйте Literate.markdown с flavor = Literate.QuartoFlavor(), чтобы конвертировать скрипты .jl в .qmd (Quarto Markdown).

• В коде применяйте специальный синтаксис:

  # # Заголовок уровня 1 → станет # Заголовок уровня 1 в .qmd
  ##| echo: false → станет #| echo: false (параметры Quarto)
  

• Шаги:

  • Установите Quarto CLI и Jupyter.

  • Сгенерируйте .qmd файл:

    Literate.markdown("script.jl", flavor=Literate.QuartoFlavor())
    

  • Рендерите через Quarto:

    quarto render script.qmd --to html
    

• Плюсы: Автоматизация, поддержка выполнения кода.

2.2 Ручное создание .qmd с Julia-кодом

• Пишите .qmd файлы напрямую, вставляя блоки кода Julia:

  ```{julia}
  #| echo: true
  x = 1 + 1
  println(x)
  ```
  

• Рендерите через Quarto CLI.

• Плюсы: Полный контроль над структурой документа.

2.3 DocumenterQuarto.jl

• Плюсы: Подходит для пакетов, интеграция с CI.

• Пакет объединяет Documenter.jl и Quarto для генерации сайтов документации.

• Генерирует шаблоны Quarto-книг с автоматическим парсингом @doc из Julia.

• Пример:

  using DocumenterQuarto
  DocumenterQuarto.generate()  # создает структуру Quarto-проекта
  

• Репозиторий: https://github.com/cadojo/DocumenterQuarto.jl

2.4 Jupyter + IJulia как бэкенд

• Quarto использует Jupyter-ядро для выполнения Julia-кода.

• Настройте ядро через kernel.json, добавив параметры Julia (например, --sysimage для ускорения):

  {
    "argv": ["julia", "--sysimage=myimage.so", "-i", ".../kernel.jl"]
  }
  

• Плюсы: Интерактивность, кеширование результатов.

3 Примеры порядка работ

3.1 Литературное программирование через Literate.jl

• Цель: Создать документ с исполняемыми примерами кода и пояснениями.

• Создайте файл example.jl с комментариями в Markdown-стиле:

  # # Линейная регрессия
  # Пример реализации линейной регрессии.
  
  using LinearAlgebra
  
  # ## Генерация данных
  # Создаем синтетические данные:
  n = 100
  x = rand(n)
  y = 2x .+ 3 .+ 0.1randn(n)
  
  # ## Обучение модели
  # Решаем уравнение методом наименьших квадратов:
  X = [ones(n) x]
  β = X \ y
  println("Коэффициенты: ", β)
  

• Конвертируйте в Markdown

  using Literate
  Literate.markdown("example.jl", "docs"; flavor=Literate.CommonMarkFlavor())
  

• Рендерите через Documenter.jl:

  using Documenter
  makedocs(sitename="Пример регрессии")
  

3.2 2. Научные отчеты через Weave.jl

• Цель: Сгенерировать PDF-отчет с графиками и вычислениями.

• Создайте файл report.jmd:

  # Анализ данных
  
  ```julia
  using Plots, CSV
  data = CSV.read("data.csv")
  plot(data.x, data.y, title="Зависимость Y от X")
  savefig("plot.png")
  ```
  
  ![](plot.png)
  

• Запустите рендеринг:

  using Weave
  weave("report.jmd", doctype="md2pdf")
  

• Результат: PDF-файл с графиком и кодом.

3.3 3. Интерактивная документация через Quarto + Julia

• Цель: Создать интерактивную веб-страницу с исполняемыми блоками.

• Создайте analysis.qmd:

  ---
  title: "Анализ"
  jupyter: julia-1.9
  ---
  
  ```{julia}
  #| echo: true
  using DataFrames
  df = DataFrame(A=1:5, B=rand(5))
  ```
  
  ```{julia}
  #| echo: false
  println("Среднее B: ", mean(df.B))
  ```
  

• Рендерите через Quarto:

  quarto render analysis.qmd --to html
  

• Результат: HTML-страница с таблицей и скрытым выводом.

3.4 4. Jupyter + IJulia для исследований

• Цель: Интерактивный анализ данных с визуализацией.

• Установите ядро:

  using IJulia
  installkernel("Julia-1.11")
  

• Создайте блокнот:

  # В Jupyter:
  using Plots
  plot(sin, 0, 2π, label="sin(x)")
  

• Результат: Ноутбук с графиком и пояснениями.

4 Сравнение подходов

• Для быстрого старта выбирайте Jupyter.
• Для публикаций — Quarto или Weave.jl.
• Для документации пакетов — Literate.jl + Documenter.