writingDemos

Table of Contents Writing Demos Title Sections Figures Tags Additional Formatting Options Example Preview your Demo

Writing Demos

Demos in PMTK3 are automatically published to html using the publishDemos() function. To ensure that these demos look nice, please format the comments as follows:

Title

Every demo should have a title. This will appear in two places, the list of demos by chapter, and at the top of the demo itself.

  * The title must be a single line, and the very first line of the file, above even the    function header. 
  * The title line must begin with two % signs followed by a single space, as in {{{%% Demo Title Here}}}.
  * Additional comments that pertain to the whole demo should immediately follow the title  without any blank lines and with each line beginning with a single % sign followed by a space. 
  * This comment block, even if empty, must end with two %% signs before the first line of Matlab code. 

Sections

Break the demo into logical sections using two %% signs. The comment text on this line is used as the section title and appears in the demos 'table' of contents.

Figures

Publishing automatically embeds any generated figures into the html document. You can control where these are placed in two ways: using %% double percent signs or by using the command.

Whenever publish encounters either of these, it immediately inserts any open figures, that have not already been inserted. The double %% signs are usually sufficient, but snapnow can be useful in loops that generate many figures. Its has no effect on the code itself.

If you do not want the %% symbol to generate a subheading, do not include any text with it.

Tags

We generate a number of tables automatically using various 'tags'. These are comment strings that begin with PMTK as in . You should include these tags in the comments as in the following:

Include the PMTKslow tag if the demo takes more than 30 seconds to run. This just excludes it from the debugDemos report. If the demo takes more than 30 minutes to run, add the PMTKreallySlow tag, which tells publishDemos() not to actually run the code, publishing only the text.

Additional Formatting Options

There are a few other formatting options. You can include arbitrary html code, bullet lists, numbered lists, _italic_, *bold*, or text, as well as external images already saved to file. Select the cell menu --> insert text markup option.

Example

The published version looks like this.

Preview your Demo

Once you're finished writing your demo, preview what the published version will look like using the previewPublish() function.

You can create a Matlab shortcut to preview the currently open document using this code: