11.11.1 Публикация файлов Octave Script

Функция publish предоставляет динамическую возможность документировать ваш файл скрипта. В отличие от статической документации, publish выполняет файл скрипта, сохраняет любые графики и вывод во время выполнения скрипта и представляет их наряду со статической документацией в требуемом формате вывода. Статическая документация может использовать Разметку публикации для улучшения и настройки вывода.

: publish (file) ¶

: publish (file, output_format) ¶

: publish (file, option1, value1, …) ¶

: publish (file, options) ¶

: output_file = publish (file, …) ¶

Генерирует отчёт из файла скрипта Octave file в одном из нескольких форматов вывода.

Сгенерированные отчёты интерпретируют Разметку публикации в комментариях к секциям, что подробно описано в руководстве GNU Octave. Комментарии к секциям — это блоки комментариев, начинающиеся со строки с двойным символом комментария.

Предположим следующий пример, использующий Разметку публикации, как содержимое файла скрипта pub_example.m:

## Headline title
#
# Some *bold*, _italic_, or |monospaced| Text with
# a <https://www.octave.org link to *GNU Octave*>.
##

# "Real" Octave commands to be evaluated
sombrero ()

%% MATLAB comment style ('%') is supported as well
%
% * Bulleted list item 1
% * Bulleted list item 2
%
% # Numbered list item 1
% # Numbered list item 2

Чтобы опубликовать этот файл скрипта, введите publish ("pub_example.m").

При вызове с одним входным аргументом генерируется HTML-отчёт в подкаталоге html относительно текущей рабочей директории. Любые команды Octave в pub_example.m вычисляются в отдельном контексте, и любые графики, созданные во время выполнения файла скрипта, включаются в отчёт.

Использование publish (file, output_format) эквивалентно вызову функции со структурой

options.format = output_format;
publish (file, options)

которая описана ниже. То же самое относится к использованию пар имя/значение

options.option1 = value1;
publish (file, options)

Структура options может иметь следующие имена полей. Если имя поля не указано, используется значение по умолчанию:

• ‘format’ — Формат вывода опубликованного файла скрипта, один из

  ‘html’ (по умолчанию), ‘doc’, ‘latex’, ‘ppt’, ‘pdf’, или ‘xml’.

  Форматы вывода ‘doc’, ‘ppt’, и ‘xml’ в настоящее время не поддерживаются. Чтобы сгенерировать отчёт ‘doc’, откройте сгенерированный отчёт ‘html’ в вашей программе офисного пакета.

  В Octave пользовательские форматы поддерживаются путем реализации всех подфункций обратного вызова в файле функции с именем ‘__publish_<custom format>_output__.m’. Чтобы получить шаблон для формата HTML, введите:

  edit (fullfile (fileparts (which ("publish")), ...
        "private", "__publish_html_output__.m"))

• ‘outputDir’ — Полный путь к каталогу, в котором будет расположен сгенерированный отчёт. Если каталог не указан, отчёт генерируется в подкаталоге html относительно текущей рабочей директории.
• ‘stylesheet’ — Не поддерживается, только для совместимости с MATLAB.
• ‘createThumbnail’ — Не поддерживается, только для совместимости с MATLAB.
• ‘figureSnapMethod’ — Не поддерживается, только для совместимости с MATLAB.
• ‘imageFormat’ — Желаемый формат для любых изображений, созданных во время оценки кода. Допустимые форматы изображений зависят от формата вывода:
  • ‘html’, ‘xml’ — ‘png’ (по умолчанию), любой формат изображения, поддерживаемый Octave
  • ‘latex’ — ‘epsc2’ (по умолчанию), любой формат изображения, поддерживаемый Octave
  • ‘pdf’ — ‘jpg’ (по умолчанию) или ‘bmp’, обратите внимание, MATLAB использует ‘bmp’ по умолчанию
  • ‘doc’ или ‘ppt’ — ‘png’ (по умолчанию), ‘jpg’, ‘bmp’ или ‘tiff’
• ‘maxWidth’ и ‘maxHeight’ — Максимальная ширина (высота) созданных изображений в пикселях. Пустое значение означает отсутствие ограничения. Оба значения должны быть заданы для правильной работы опции.

  ‘[]’ (по умолчанию), целое значение ≥ 0

• ‘useNewFigure’ — Использовать новое окно графиков для графиков, созданных вычисленным кодом. Это предотвращает побочные эффекты с уже открытыми окнами графиков.

  ‘true’ (по умолчанию) или ‘false’

• ‘evalCode’ — Вычислять код файла Octave-источника

  ‘true’ (по умолчанию) или ‘false’

• ‘catchError’ — Ловить ошибки при вычислении кода и продолжать

  ‘true’ (по умолчанию) или ‘false’

• ‘codeToEvaluate’ — Команды Octave, которые должны быть вычислены перед публикацией файла скрипта. Эти команды Octave не отображаются в сгенерированном отчёте.
• ‘maxOutputLines’ — Максимальное количество строк вывода из оценки кода, которые включаются в вывод.

  ‘Inf’ (по умолчанию) или целое значение > 0

• ‘showCode’ — Отображать вычисленные команды Octave в сгенерированном отчёте

  ‘true’ (по умолчанию) или ‘false’

Вариант вывода output_file — это строка с путём и именем файла сгенерированного отчёта.

См. также: grabcode.

Противоположностью publish является grabcode:

: grabcode (url) ¶

: grabcode (filename) ¶

: code_str = grabcode (…) ¶

Извлекает код из отчёта, созданного функцией publish.

Извлечённый код внутри опубликованного отчёта должен быть заключён в строки ‘##### SOURCE BEGIN #####’ и ‘##### SOURCE END #####’. Функция publish автоматически создаёт этот формат.

Если значение возврата не запрашивается, код сохраняется во временном файле и открывается в стандартном редакторе. ПРИМЕЧАНИЕ: временный файл должен быть сохранён под новым именем, иначе код будет потерян.

Если запрос на вывод, извлечённый код будет возвращён как строка code_str.

Пример:

publish ("my_script.m");
grabcode ("html/my_script.html");

В примере выше my_script.m публикуется по умолчанию в html/my_script.html. Затем опубликованный Octave-скрипт извлекается для редактирования его содержимого в новом временном файле.

См. также: publish.