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

Generate an HTML view of a MATLAB script including the code, results, and comments.

Copy the example file fourier_demo2.m to your current folder.

filename = fullfile(matlabroot,'help','techdoc','matlab_env','examples','fourier_demo2.m');
copyfile(filename,'.','f')

Use the publish function to run the example and generate an HTML view of the example. Then, 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

Generate a Microsoft^® Word view of a MATLAB script including the code, results, and comments.

Copy the example file fourier_demo2.m to your current folder.

filename = fullfile(matlabroot,'help','techdoc','matlab_env','examples','fourier_demo2.m');
copyfile(filename,'.','f')

Use the publish function to generate a Microsoft Word view of the example. Then, use the winopen function to view the resulting file.

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

Customize View Using Name-Value Pairs

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

Copy the example file fourier_demo2.m to your current folder.

filename = fullfile(matlabroot,'help','techdoc','matlab_env','examples','fourier_demo2.m');
copyfile(filename,'.','f')

Use the publish function to generate an HTML view of the example. SpecifyfigureSnapMethod as 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 Using Structure

Use a structure to create a Microsoft Word view of a MATLAB 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.

Copy the example file fourier_demo2.m to your current folder.

filename = fullfile(matlabroot,'help','techdoc','matlab_env','examples','fourier_demo2.m');
copyfile(filename,'.','f')

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

options_doc_nocode.format = 'doc';
options_doc_nocode.showCode = false;

Use the publish function to generate a Microsoft Word view of the example using the options specified in options_doc_nocode. Then, use the winopen function to view the resulting file.

publish('fourier_demo2.m',options_doc_nocode);
winopen('html/fourier_demo2.doc')

Save File Path of Published Script to Variable

Generate an HTML view of a MATLAB script, and save the path of the published HTML file to a variable.

Copy the example file fourier_demo2.m to your current folder.

filename = fullfile(matlabroot,'help','techdoc','matlab_env','examples','fourier_demo2.m');
copyfile(filename,'.','f')

Use the publish function to generate an HTML view of the example, and save the path of the published HTML file to the variable mydoc.

mydoc = publish('fourier_demo2.m')

mydoc =

C:\myMATLABfiles\html\fourier_demo2.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: 'myfile.m'

Example: '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 Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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.

'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: '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: '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' | 'entireFigureWindow'

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
'entireFigureWindow'	Included	Included	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 'entireFigureWindow'. 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, you can set the value of an input argument for a function being published.

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

'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

• In MATLAB Online, you cannot use the publish function on a file in your Shared folder. To publish a shared file, open the file in the Editor, and then click Publish on the toolbar. When you use the Publish button in MATLAB Online instead of the publish function, MATLAB stores the results in the Published subfolder of your root folder instead of the html subfolder.

Tips

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