---
name: publishing-tutorials-examples
description: Use when converting an ISETCam tutorial or example .m file into a self-contained HTML file for a wiki page — iePublish, s_publishTutorials, s_publishExamples, embedding figures or movies, or GitHub Pages/wiki linking.
---

# Publishing Tutorials and Examples

ISETCam provides `iePublish` and the `s_publish*.m` helper scripts for
converting MATLAB tutorials and examples into HTML files that can be linked
from wiki pages.

The publishing helpers are intended to create self-contained HTML files.
Figures are embedded directly in the HTML as base64 images, so the result
can be served as one file without copying a companion folder of PNG files.

## Publish One File

From a MATLAB session with ISETCam on the path:

```matlab
htmlFile = iePublish('tutorials/scene/t_sceneIntroduction.m');
web(htmlFile, '-browser');
```

For tutorials in a dependent repository, pass the full path to the source
script after that repository is on the MATLAB path:

```matlab
htmlFile = iePublish(fullfile(isetbioRootPath, ...
    'tutorials', 'cmosaic', 't_cMosaicBasic.m'));
```

`iePublish` writes the HTML file next to the source `.m` file, using the
same base name and the `.html` extension.

## Publish a Set of Files

ISETCam provides these batch scripts:

```matlab
s_publishTutorials
s_publishExamples
```

Both scripts call `iePublish` with `imageFormat` set to `'inline'`. This is
the setting that embeds figures in the HTML and makes the output suitable
for serving from a web page and linking from a wiki.

The default `s_publishTutorials` run publishes all known ISETCam tutorial
directories. The default `s_publishExamples` run currently publishes the
selected example directory listed in the script; edit `sDir` in that file to
publish a different example subset.

## Useful Options

The defaults are chosen for wiki-linkable tutorial output:

```matlab
htmlFile = iePublish(sourceFile, ...
    'evalCode', true, ...
    'showCode', true, ...
    'imageFormat', 'inline', ...
    'maxHeight', 512, ...
    'maxWidth', 512);
```

Common adjustments are:

- `evalCode`: Set to `false` for a quick code-only preview. Figures and
  command output are only regenerated when this is `true`.
- `showCode`: Set to `false` when the HTML should show output without source
  code.
- `maxHeight` and `maxWidth`: Resize embedded figures for more manageable
  HTML pages.
- `catchError`: Leave as `true` for most publishing runs so one script error
  does not terminate a batch unexpectedly.
- `stylesheet`: Pass a CSS file when a project needs custom HTML styling.

For wiki-linked pages, keep `imageFormat` set to `'inline'`. Other formats,
such as `'png'`, require the external image files to be copied and linked
along with the HTML file.

## Embedded Movies

Small MP4 movies can be embedded in the generated HTML. Write the movie next
to the source file while publishing, then add a prose marker comment with
the relative movie file name:

```matlab
movieFile = fullfile(fileparts(mfilename('fullpath')), 'exampleMovie.mp4');
ieMovie(movieData, 'vname', movieFile, 'show', false, 'FrameRate', 8);
%%
% iePublishVideo: exampleMovie.mp4
```

With the default inline publishing mode, `iePublish` replaces that marker
with a self-contained HTML `<video>` element and deletes the temporary MP4.

Keep `%%` and `% iePublishVideo: ...` on separate lines as shown above.
Combining them into one `%% iePublishVideo: ...` cell-title line renders as
an HTML heading (`<h2>`) instead of a paragraph (`<p>`), and `iePublish`'s
marker regex only matches `<p>` text — the video then silently never gets
embedded, with no error to flag it.

Build movie frames from plain numeric data and hand the whole stack to
`ieMovie` directly, rather than rendering a plot and screen-capturing it
(`getframe`, `exportgraphics`) inside the frame loop. Under `publish`-driven
execution (which `iePublish` uses), a figure updated and captured mid-loop
can come back solid black regardless of the figure's `Visible` setting —
this is an interaction with how `publish` manages figures, not specific to
one script or renderer. If a frame needs annotation (title, colorbar, axis
labels) that raw intensity data can't show, render that as a separate
static figure outside the movie loop instead of trying to bake it into
every video frame.
Keep embedded movies short and modest in size so the HTML file stays
reasonable.

## GitHub and Wiki Links

The generated files are ordinary HTML and should render correctly when
served as HTML, for example from GitHub Pages or another static web server.
A GitHub repository `blob` URL may show the HTML source instead of rendering
the page; use a served HTML URL when linking from wiki pages.

## Recommended Workflow

1. Edit and run the tutorial or example interactively.
2. Close unrelated figures and make sure the script runs without manual
   input.
3. Publish the script with `iePublish`, `s_publishTutorials`, or
   `s_publishExamples`.
4. Open the generated HTML locally and inspect the figures, output, and
   links.
5. Commit the source `.m` file and the generated `.html` file when the
   project tracks published HTML.
6. Link the served HTML file from the relevant wiki page.

Re-run the publisher whenever the source tutorial or example changes.
Embedded figures make the generated HTML self-contained, but they can also
make the file large, so use the figure-size options when a script creates
large displays.