11.11.1 Публикация файлов скриптов Octave

Функция 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 filename

: grabcode url

: 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.