11.11.1 Publish Octave Script Files

The function publish provides a dynamic possibility to document your script file. Unlike static documentation, publish runs the script file, saves any figures and output while running the script, and presents them alongside static documentation in a desired output format. The static documentation can make use of Publishing Markup to enhance and customize the output.

: publish (file)

: publish (file, output_format)

: publish (file, option1, value1, …)

: publish (file, options)

: output_file = publish (file, …)

Generate a report from the Octave script file file in one of several output formats.

The generated reports interpret any Publishing Markup in comments, which is explained in detail in the GNU Octave manual. Assume the following example, using some Publishing Markup, to be the contents of the script file 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

To publish this script file, type publish ("pub_example.m").

With only file given, a HTML report is generated in a subdirectory html relative to the current working directory. The Octave commands are evaluated in a separate context and any figures created while executing the script file are included in the report. All formatting syntax of file is treated according to the specified output format and included in the report.

Using publish (file, output_format) is equivalent to the function call using a structure

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

which is described below. The same holds for using option/value pairs

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

The structure options can have the following field names. If a field name is not specified, the default value is used:

• ‘format’ — Output format of the published script file, one of

  ‘html’ (default), ‘doc’, ‘latex’, ‘ppt’, ‘pdf’, or ‘xml’.

  The output formats ‘doc’, ‘ppt’, and ‘xml’ are not currently supported. To generate a ‘doc’ report, open a generated ‘html’ report with your office suite.

  In Octave custom formats are supported by implementing all callback subfunctions in a function file named ‘__publish_<custom format>_output__.m’. To obtain a template for the HTML format type:

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

• ‘outputDir’ — Full path of the directory where the generated report will be located. If no directory is given, the report is generated in a subdirectory html relative to the current working directory.
• ‘stylesheet’ — Not supported, only for MATLAB compatibility.
• ‘createThumbnail’ — Not supported, only for MATLAB compatibility.
• ‘figureSnapMethod’ — Not supported, only for MATLAB compatibility.
• ‘imageFormat’ — Desired format for any images produced while evaluating the code. The allowed image formats depend on the output format:
  • ‘html’, ‘xml’ — ‘png’ (default), any image format supported by Octave
  • ‘latex’ — ‘epsc2’ (default), any image format supported by Octave
  • ‘pdf’ — ‘jpg’ (default) or ‘bmp’, note MATLAB uses ‘bmp’ as default
  • ‘doc’ or ‘ppt’ — ‘png’ (default), ‘jpg’, ‘bmp’, or ‘tiff’
• ‘maxWidth’ and ‘maxHeight’ — Maximum width (height) of the produced images in pixels. An empty value means no restriction. Both values must be set in order for the option to work properly.

  ‘[]’ (default), integer value ≥ 0

• ‘useNewFigure’ — Use a new figure window for figures created by the evaluated code. This avoids side effects with already opened figure windows.

  ‘true’ (default) or ‘false’

• ‘evalCode’ — Evaluate code of the Octave source file

  ‘true’ (default) or ‘false’

• ‘catchError’ — Catch errors while evaluating code and continue

  ‘true’ (default) or ‘false’

• ‘codeToEvaluate’ — Octave commands that should be evaluated prior to publishing the script file. These Octave commands do not appear in the generated report.
• ‘maxOutputLines’ — Maximum number of output lines from code evaluation which are included in output.

  ‘Inf’ (default) or integer value > 0

• ‘showCode’ — Show the evaluated Octave commands in the generated report

  ‘true’ (default) or ‘false’

The option output output_file is a string with path and file name of the generated report.

See also: grabcode.

The counterpart to publish is grabcode:

: grabcode (url)

: grabcode (filename)

: code_str = grabcode (…)

Grab the code from a report created by the publish function.

The grabbed code inside the published report must be enclosed by the strings ‘##### SOURCE BEGIN #####’ and ‘##### SOURCE END #####’. The publish function creates this format automatically.

If no return value is requested the code is saved to a temporary file and opened in the default editor. NOTE: The temporary file must be saved under a new or the code will be lost.

If an output is requested the grabbed code will be returned as string code_str.

Example:

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

The example above publishes my_script.m to the default location html/my_script.html. Next, the published Octave script is grabbed to edit its content in a new temporary file.

See also: publish.