(octave.info)Publish Octave Script Files
11.10.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 Note: 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: Note: 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: Note: publish.
automatically generated by info2www version 1.2.2.9