Learn more about MATLAB

publish - Publish M-file containing cells, save output to specified file type

Syntax

publish('file') publish('file','format') publish('file', options) my_doc = publish('file',...)

Description

publish('file') publishes file.m by running it in the base workspace, one cell at a time. It saves the code, comments, and results to an HTML output file. MATLAB stores the output file, file.html, along with other supporting output files in an html subfolder of the folder containing file.m.

publish('file','format') publishes file.m by running it in the base workspace, one cell at a time. It saves the code, comments, and results to an output file, file.format. Regardless of the format, MATLAB stores this output file, along with other supporting output files, in an html subfolder of the folder containing file.m.

publish('file', options) publishes file.m using the structure options.

my_doc = publish('file',...) returns the output resulting from publishing file.m to my_doc.

Inputs

file

Specifies the M-file to publish.

format

Specifies the format to which you want to publish the file. Valid formats appear in the "Options for the publish Function" table later in this section.

options

A structure with the fields listed in the following table.

Options for the publish Function

Field

Values

format

Specifies the output format for the published document, as follows:

'doc'—Specifies Microsoft Word output format.
'latex'—Specifies LaTeX output format.
'ppt'—Specifies Microsoft PowerPoint output format.
'xml'—Specifies Extensible Markup Language output format.
'pdf'—Specifies Portable Document Format output format.
If you specify 'pdf', then you must specify imageFormat as '.bmp' (the default) or '.jpg'.
'html' (default)—Specifies Hypertext Markup Language output format.
If you specify html, MATLAB includes the M-file code at the end of the published HTML file as comments, even when you set the showCode option to false. Because MATLAB includes the M-file code as comments, the code does not display in a Web browser. Use the grabcode function to extract the code from the HTML file.

stylesheet

Specifies the Extensible Stylesheet Language (XSL) file that you want MATLAB to use when you specify a format of 'html', 'xml', or 'latex' as follows:

'' (default)—The MATLAB default stylesheet
XSL file name—The full path of the XSL file

outputDir

Specifies the folder to which you want MATLAB to publish the output document and its associated image files, as follows:

'' (default)—MATLAB places output in an html subfolder of the current folder, which MATLAB creates.
full path—MATLAB places output in the specified folder

imageFormat

Specifies the file type for images that MATLAB produces when publishing M-files.

'png' (default unless format is latex or pdf)
'epsc2' (default when format is latex)
'bmp' (default when format is 'pdf')
Alternatively, '.jpg' when the format is 'pdf'
Any format supported by print when figureSnapMethod is print, unless format is pdf
Any format supported by imwrite when figureSnapMethod is getframe, entireFigureWindow, or entireGUIWindow, unless format is pdf

figureSnapMethod

Specifies how figure windows and GUI dialog boxes that the M-file code creates appear in published documents. Window decorations are the title bar, toolbar, menu bar, and window border.

Values	Window Decorations for ...		Background Color for ...
	GUIs	Figures	GUIs	Figures
'entireGUIWindow' (default)	Included	Excluded	Match screen	White
'print'	Excluded	Excluded	White	White
'getframe'	Excluded	Excluded	Match screen	Match screen
'entireFigureWindow'	Included	Included	Match screen	Match screen

useNewFigure

A logical value that specifies whether MATLAB creates a Figure window for figures that the M-file code generates, as follows:

true (default) specifies that if the M-file code generates a figure, then MATLAB create a Figure window with a white background and at the default size before publishing.
false specifies that you do not want MATLAB to create a figure window.
This value enables you to use a figure with different properties for publishing. Open a Figure window, change the size and background color, for example, and then publish. Figures in your published document use the characteristics of the figure you opened before publishing.

maxHeight

Specifies the maximum height, in pixels, for an image that the M-file code generates, as follows:

[] (default)—Height is unrestricted. Always used when the format is pdf.
Height is unrestricted. Always used when the format is pdf.
Any positive integer—Height is the specified value.
Height is the specified value.

maxWidth

Specifies the maximum width, in pixels, for an image that the M-file code generates, as follows:

[] (default)—Width is unrestricted. Always used when the format is pdf.
Any positive integer—Width is the specified value.

showCode

Logical value that specifies whether MATLAB includes the M-file code in the published document:

true (default)
false

evalCode

Logical value that specifies whether MATLAB runs the code that it is publishing.

true (default)
Use this option if you want to run the code. If set to true and you are publishing a function M-file that requires inputs, you must also specify the codeToEvaluate option.
false
Use this option if you do not want to run the code, but do want to present it (without output) in the published document.

catchError

Logical value that specifies what MATLAB does if there is an error in the code that it is publishing:

true (default)—MATLAB continues publishing and includes the error in the published file
false—MATLAB displays the error and publishing ends

codeToEvaluate

Specifies the code that MATLAB is to evaluate. By default, MATLAB evaluates the code in the M-file you are publishing.

createThumbnail

Logical value that specifies whether MATLAB creates a thumbnail image of the published document:

true (default)
false

maxOutputLines

Value that specifies the maximum number of output lines per M-file cell that you want to publish before truncating the output.

Inf (default)—Includes all output lines
nonnegative integer—Includes at most the number of lines specified

Examples

Copy sine_wave.m, publish it to HTML, and then view the published document:

copyfile(fullfile(docroot,'techdoc','matlab_env','examples', ...
'sine_wave.m'),'.','f')

% When you run the command that follows, MATLAB runs sine_wave.m, 
% and saves the code, comments, and results to 
% /html/sine_wave.html:

publish('sine_wave.m', 'html')

% View the published output file in the Web browser:
web('html/sine_wave.html')

Copy sine_wave.m, publish it to Microsoft Word format by using a structure, and then view the published document:

copyfile(fullfile(docroot,'techdoc','matlab_env','examples', ...
'sine_wave.m'),'.','f')

% Define the structure, options_doc_nocode, 
% to exclude code from the output 
% and publish to Microsoft World format:
options_doc_nocode.format='doc'
options_doc_nocode.showCode=false

% Publish sine_wave.m:
publish('sine_wave.m',options_doc_nocode)

% View the published output file in Microsoft Word:
winopen('html/sine_wave.doc')

Copy collatz.m, create a structure to specify the input values, publish it to HTML, and then view the published document:

copyfile(fullfile(docroot,'techdoc','matlab_env','examples', ...
'collatz.m'),'.','f')

% Create a structure, opts, that contains the code that you 
% want collatz.m to evaluate when it runs:
opts.codeToEvaluate = 'n = 3; collatz(n)';

% In the MATLAB Web browser, display the results of
% publishing collatz.m when it runs with the values 
% specified in opts:
web(publish('collatz',opts))

Copy sine_wave.m, publish it capturing window decorations, and then view the published document:

copyfile(fullfile(docroot,'techdoc','matlab_env','examples', ...
'sine_wave.m'),'.','f')

% Create an options file that causes the published document
%  to capture window decorations:
function_options.format='html';
function_options.figureSnapMethod='entireGUIWindow';

% Publish the script using the options file:
publish('sine_wave.m',function_options);

% View the output in the MATLAB Web browser
web('html/sine_wave.html')

Publish an M-File demo file to PDF, and then open the published document:

open(publish('sparsity',struct('format','pdf','outputDir',tempname)))

Alternatives

To publish an M-File from the desktop:

Open the M-File you want to publish in the Editor.
Choose one of the following:
- To publish with default options, choose File > Publish filename.
- To publish with customized options, choose File > Publish Configuration for filename > Edit Publish Configurations for filename, and then adjust the Publish settings.