publish

Generate view of MATLAB file in specified format

Syntax

publish(file)

publish(file,format)

publish(file,Name,Value)

publish(file,options)

my_doc = publish(file,___)

Description

publish(file) generates a view of the specified MATLAB^® code file and output in an HTML format that can be used for sharing. publish saves the HTML file and a file for each graphic that the code creates in a subfolder named html. The location of the html subfolder is relative to the location of file.

For example, publish('C:\myMATLABfiles\myfile.m') runs the code in myfile.m using the base workspace, and then saves the formatted code and results in C:\myMATLABfiles\html\myfile.html.

publish(file,format) generates a view of the specified MATLAB file in the specified file format. All file formats save to the html subfolder.

publish(file,Name,Value) generates a view of the specified MATLAB file with options specified by one or more name,value pair arguments.

publish(file,options) uses the options structure to generate the view of the specified MATLAB file. Using a structure to specify options is useful when you want to preconfigure and save your options for repeated use. The fields and values of the options structure correspond to names and values of name-value pair arguments.

my_doc = publish(file,___) generates a view of the specified MATLAB file and returns the path of the resulting output file. You can use this syntax with any of the input argument combinations in the previous syntaxes.

Examples

Generate HTML View of MATLAB Script

Create an HTML view of a MATLAB example script including the code, results, and comments. Use the web function to view the resulting file.

publish("fourier_demo2.m");
web("html/fourier_demo2.html")

Generate View of MATLAB Script in Microsoft Word Format

Create a Microsoft® Word view of a MATLAB example script including the code, results, and comments. Save the path of the published file to a variable. Use the winopen function to view the resulting file.

mydoc = publish("fourier_demo2.m","doc");
winopen(mydoc)

Customize View of MATLAB Script Using Name-Value Arguments

Use name-value arguments to change the appearance of published figure windows in the HTML view of a MATLAB example script.

Use the "figureSnapMethod" name-value argument with the value "entireFigureWindow" to include window decorations and to match the figure background color to the screen color for figures. Then, use the web function to view the resulting file.

publish("fourier_demo2.m","figureSnapMethod","entireFigureWindow");
web("html/fourier_demo2.html")

Customize View of MATLAB Script Using Structure

Use a structure to create a Microsoft Word view of a MATLAB example script that does not show the code from the script. Specifying options as a structure is useful when you want to preconfigure and save your options for repeated use.

Create a structure options that specifies the format and showcode options.

options.format = "doc";
options.showCode = false;

Create a Microsoft Word view of the example using the options specified in options. Use the winopen function to view the resulting file.

publish("fourier_demo2.m",options);
winopen("html/fourier_demo2.doc")

Generate HTML View of MATLAB Function with Input Arguments

Generate an HTML view of a MATLAB function that requires input arguments.

Create and save the function fact.m.

%% FACT compute the factorial of a number
% FACT(N) computes the factorial of the number N and returns the results 
function f = fact(n)
    f = prod(1:n);
end

Use the publish function to generate an HTML view of the function. Set the value of the input argument n by using the codeToEvaluate name-value argument. Then, use the web function to view the resulting file.

publish("fact.m","codeToEvaluate","fact(5);");
web("html/fact.html")

Input Arguments

file — MATLAB file name

character vector | string

MATLAB file name, specified as a character vector or string. file can include a full or partial path.

Note

When MATLAB publishes a file, it can overwrite existing files from the output folder that start with the same name as file.

Example: publish('myfile.m')

Example: publish('C:\myMATLABfiles\myfile.m')

format — Output format

'html' (default) | 'doc' | 'latex' | 'ppt' | 'xml' | 'pdf'

Output format of published file, specified as one of the values listed in the table.

Value	Output Format
'html' (default)	Hypertext Markup Language
'doc'	Microsoft® Word
'latex'	LaTeX
'ppt'	Microsoft PowerPoint®
'xml'	Extensible Markup Language
'pdf'	Portable Document Format (PDF)

The Microsoft Word and Microsoft PowerPoint formats are only available on Windows^® platforms.

MATLAB does not preserve syntax highlighting when you specify the output format as Microsoft PowerPoint or LaTeX.

Example: publish('myfile.m','ppt');

options — Options for published output

structure

Options for published output, specified as a structure. Use the options structure instead of name-value pair arguments when you want to reuse the same configuration for publishing multiple MATLAB files.

The fields and values of the options structure correspond to names and values of the name-value pair arguments.

For example, this command creates the structure options, and specifies the PDF output format and the output folder C:\myPublishedOutput.

options = struct('format','pdf','outputDir','C:\myPublishedOutput')

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'format','pdf','showCode',false specifies the PDF output file format and excludes the code from the output.

Output Options

format — Output format

'html' (default) | 'doc' | 'latex' | 'ppt' | 'xml' | 'pdf'

Output format of published file, specified as one of the values listed in the table.

Value	Output Format
'html' (default)	Hypertext Markup Language (HTML)
'doc'	Microsoft Word
'latex'	LaTeX
'ppt'	Microsoft PowerPoint
'xml'	Extensible Markup Language
'pdf'	Portable Document Format (PDF)

The Microsoft Word and Microsoft PowerPoint formats are only available on Windows platforms.

MATLAB does not preserve syntax highlighting when you specify the output format as Microsoft PowerPoint or LaTeX.

Example: publish('myfile.m','format','pdf')

outputDir — Output folder

character vector

Output folder to which the published document is saved, specified as a character vector. Specify the full path of the folder.

Example: publish('myfile.m','outputDir','C:\myPublishedOutput')

stylesheet — Extensible Stylesheet Language (XSL) file

character vector

Extensible Stylesheet Language (XSL) file to use when publishing a MATLAB file to HTML, XML, or LaTeX format, specified as a character vector. Specify the full path of the XSL file.

Example: publish('myfile.m','stylesheet','C:\myStylesheet\stylesheet.xsl')

Figure Options

createThumbnail — Whether to create thumbnail image

true (default) | false

Whether to create a thumbnail image for the published document, specified as true or false. You can use the generated thumbnail to display a small representation of your file on HTML pages.

figureSnapMethod — Figure window appearance

'entireGUIWindow' (default) | 'print' | 'getframe'

Figure window appearance for the published document, specified as one of the values listed in the table. Figure window appearance includes the background color of the plot and whether it includes window decorations (title bar, toolbar, menu bar, and window border).

This option is not available in MATLAB Online™.

Value	Window Decorations		Background Color
	GUIs	Figures	GUIs	Figures
'entireGUIWindow' (default)	Included	Excluded	Matches screen	White
'print'	Excluded	Excluded	White	White
'getframe'	Excluded	Excluded	Matches screen	Matches screen

imageFormat — Image file format

'png' | 'epsc2' | 'jpg' | ...

Image file format for the images in the published document, specified as one of the values listed in the table. The list of valid image formats depends on the specified output format.

Output Format	Valid Image Formats	Default Image Format
Microsoft Word	Any image format that your installed version of Microsoft Office can import, including 'png' , 'jpg', 'bmp', and 'tiff'. If the 'figureSnapMethod' option is set to 'print', then you also can specify 'eps', 'epsc', 'eps2', 'ill', 'meta', and 'pdf'.	'png'
Hypertext Markup Language (HTML)	All image formats. Ensure that the tools you use to view and process the output files can display the output format you specify.	'png'
LaTeX	All image formats. Ensure that the tools you use to view and process the output files can display the output format you specify.	'epsc2' The default changes to 'png' in these cases: figureSnapMethod is 'getframe'. figureSnapMethod is 'entireGUIWindow' and the snapped window is a GUI window.
Portable Document Format (PDF)	'bmp' and 'jpg'.	'bmp'
Microsoft PowerPoint	Any format that your installed version of Microsoft Office can import, including 'png', 'jpg', 'bmp', and 'tiff'.	'png'
Extensible Markup Language (XML)	All image formats. Ensure that the tools you use to view and process the output files can display the image format you specify.	'png'

maxHeight — Maximum image height

[] (default) | positive integer

Maximum image height of the published images, specified as one of these values:

• [] (default) — Unrestricted height. This value is always used when the output format is PDF.

• Positive integer — Height in pixels.

maxWidth — Maximum image width

[] (default) | positive integer

Maximum image width of the published images, specified as one of these values:

• [] (default) — Unrestricted width. This value is always used when the output format is PDF.

• Positive integer — Width in pixels.

useNewFigure — Whether to create new figure

true (default) | false

Whether to create new figure, specified as true or false. If true and the code generates a figure, then MATLAB creates a new figure window in the default size with a white background before publishing. If false, MATLAB does not create a figure window.

Specifying a value of false is useful if you want to use a figure with different properties for publishing. For example, you can open a figure window, change the size and background color, and then publish your code. Figures in your published document use the characteristics of the figure you opened before publishing.

Code Options

evalCode — Whether to run code

true (default) | false

Whether to run the code and include the MATLAB output in the published view, specified as true or false.

catchError — Whether to catch errors

true (default) | false

Whether to catch errors during publishing, specified as true or false. If true and an error occurs, MATLAB continues publishing and includes the error in the published file. If false and an error occurs, MATLAB displays the error at the command line and does not produce a published file.

codeToEvaluate — Additional code to run

character vector

Additional code to run during publishing, specified as a character vector. Use this option to run code that is not included in the MATLAB file. For example, when publishing a function, you can set the value of input arguments.

If this option is unspecified, MATLAB only runs the code in the MATLAB file you are publishing.

Example: publish('myfunction.m','codeToEvaluate','myfunction(1,10)')

maxOutputLines — Maximum number of lines

Inf (default) | nonnegative integer value

Maximum number of lines of output to be included in the published document, specified as one of these values:

• Inf (default) — MATLAB includes all output in the published document.

• Nonnegative integer — MATLAB only includes the specified number of lines in the published document. Setting this option is useful if a smaller, representative sample of the output suffices.

showCode — Whether to include code

true (default) | false

Whether to include code in published file, specified as true or false.

If the output format is HTML, MATLAB includes the code at the end of the published HTML file as comments, even when you set the 'showCode' option to false. Including the code as comments enables the grabcode function to extract the MATLAB code from an HTML file, even when the file does not display the code. The code does not display in a Web browser because MATLAB includes the code as comments.

Limitations

• The publish function does not include formatted text when generating a view of a live script or function (.mlx). To generate a view of the entire live script or live function, use the export function instead.

• Publishing a MATLAB code file (.m) by calling the publish function from a live script or function (.mlx) is not supported.

• The publish function does not support the input function. Publishing a MATLAB code file (.m) that contains a call to the input function results in an error.

Tips

• To enhance the readability of the published document and include additional image snapshots, external file content, and external images, see Publishing Markup.

• To avoid duplicate snapshots when publishing MATLAB code files, make sure that your cursor is not positioned over any figures before calling the publish function. Having the cursor on a figure can cause the figure to update and the publish function to generate duplicate snapshots.

Version History

Introduced before R2006a

R2024b: 'entireFigureWindow' value for figureSnapMethod option will not be supported

The 'entireFigureWindow' value for the figureSnapMethod option will not be supported in a future release. Use the 'entireGUIWindow', 'print', or 'getframe' values instead.