updatingDocumentation

1. summary Information about updating the PMTK3 documentation

Most of the documentation for PMTK3 is generated by the following Matlab scripts.

Most of these scripts rely on hard coded, user dependent paths set in the config.txt file; make sure these are correct before running the scripts. If you have a config-local.txt file, any listed property value pairs override those in config.txt.

All of these scripts require Matlab, and will probably not work under Octave. They have only been tested on 32 bit windows, Matlab version 2010a.

publishDemos and generateSynopses both update their respective wiki pages automatically. For this to work, you need to have a locally checked out copy of the wiki branch of the svn repository. Remember to check in changes made to this local wiki repository after running these scripts.

• Documentation*

  * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/reports/publishTutorial.m publishTutorial]

 This script generates the [http://code.google.com/p/pmtk3/wiki/Tutorial pmtk tutorial] pages. It uses  [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/reports/pmtkPublish.m pmtkPublish.m], which is like the built-in publish command, except it first expands pmtk filenames into their googlecode urls. 

  * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/reports/publishDemos.m publishDemos] 

 This script should be run overnight as it can take many hours to complete. It updates [Demos these tables] and republishes all of the demos. If you only want to regenerate the tables, and not rerun the demos (thus taking only a minute), set wikiOnly to true at the top of the file. This script interacts with PML to determine on which pages in the book the demos are referenced. PML must be fully compiled. publishDemos calls the [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/reports/sub/publishFolder.m publishFolder] function to publish each demo folder. You can use this to republish a single folder; see it for additional defaults such as tag based exclusions. If the demos directory structure has changed significantly, delete the contents of docs/demoOutput first.

 * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/reports/generateSynopses.m generateSynopses]

 This script takes about 10 seconds to run, and generates [synopsisPages these tables].

  * [http://code.google.com/p/pmtk3/source/browse/trunk/pmtkTools/reports/generateModelsVsMethodsTables.m generateModelsVsMethodsTables]

 This script takes a few seconds to run and generates [ModelsByMethods these tables] showing PMTK models and the methods they support. Models are included and grouped according to the [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/reports/classNameMappings.m classNameMappings.m] file.  The 'methods' are inferred based on toolbox file names that begin with a known model name. The script also includes a list of excluded directories such as sub, which are not searched. 

  * [http://code.google.com/p/pmtk3/source/browse/trunk/pmtkTools/reports/generateModelLists.m generateModelLists.m]

 This script takes about a minute to run and generates [http://code.google.com/p/pmtk3/wiki/modelLists these tables] listing the models in PMTK. The script looks for PMTKdefn tags in model constructors, formats the latex text it finds, and embeds the generated image into the table. It will error if the text found is invalid latex code. The text is automatically surrounded by $ symbols if not present. The idea is that you can give a mathematical equation defining the model, so that all models can be listed together with their equations. However we currently only do this for basicModels. 

  * [http://code.google.com/p/pmtk3/source/browse/trunk/pmtkTools/reports/classNameMappings.m classNameMappings]

 This contains a cell array that specifies which models belong in each class e.g., deepBelNet is a kind of latent variable model. This should be updated whenever a new class is added. This information is needed by  [http://code.google.com/p/pmtk3/source/browse/trunk/pmtkTools/reports/generateModelsVsMethodsTables.m generateModelsVsMethodsTables] and [http://code.google.com/p/pmtk3/source/browse/trunk/pmtkTools/reports/generateModelLists.m generateModelLists.m].

• Testing*

  * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/testing/debugDemos.m debugDemos]

 debugDemos runs most of the demos, capturing warnings and errors along the way. Figures generated by these demos are not displayed. The scripts runs in about 20 minutes depending on the exclusion tags at the top of the file. You must always exclude PMTKinteractive. It generates [http://pmtk3.googlecode.com/svn/trunk/docs/debugReport.html this table] .

  * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/testing/runAllDemos.m runAllDemos] Runs most of the demos in the demos directory; this file is auto-generated by [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/testing/makeRunDemos.m makeRunDemos]

• Meta-documentation*

 This script takes about 30 seconds to run, and generates [http://pmtk3.googlecode.com/svn/trunk/docs/authors/fileAuthors.html this table] of contributed files. 

  * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/reports/generateAuthorLocReport.m generateAuthorLocReport]

 This script takes about 30 seconds to run, and generates [http://pmtk3.googlecode.com/svn/trunk/docs/authors/authorsLOC.html this table], showing the lines of code contributed by various authors. 

  * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/supportTools/generateSupportReport.m generateSupportReport]

 This script takes only a few seconds to run, and generates [http://pmtksupport.googlecode.com/svn/trunk/docs/authors/packageAuthors.html this table] of supporting packages. You must have a local copy of the pmtkSupport [http://code.google.com/p/pmtksupport/source/checkout svn repository]. The html report is stored in the pmtkSupport repository. See [http://code.google.com/p/pmtksupport/wiki/addingNewPackages this page] for details on adding and updating packages.

  * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/reports/generatePmtkStats.m generatePmtkStats]

 This script takes about 30 seconds to run, and generates [http://pmtk3.googlecode.com/svn/trunk/docs/pmtkStats.html this table].

  * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/dataTools/generatePmtkDataTable.m generatePmtkDataTable]

 This script about 30 seconds to run, generating [http://pmtkdata.googlecode.com/svn/trunk/docs/dataTable.html this table]. You must have a local copy of the [http://pmtkData.googlecode.com pmtkData] svn repository. The html table is stored in the pmtkData repository. See [http://code.google.com/p/pmtkdata/wiki/GuidelinesForContributors this page] for details on adding new data sets.

• Book stuff*

  * [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/pml/pmlMissingCodeReport.m pmlMissingCodeReport] 

 This script generates an html table of code referenced in PML that can not be found. It includes the page numbers on which the code is referenced. Like publishDemos above, this script uses [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/pml/pmlChapterPages.m pmlChapterPages], and [http://pmtk3.googlecode.com/svn/trunk/pmtkTools//pml/pmlCodeRefs.m pmlCodeRefs] to parse the latex code.ind, and pml.toc files. PML must be fully compiled. 

  *  [http://pmtk3.googlecode.com/svn/trunk/pmtkTools/pml/pmlFigureCodeReport.m pmlFigureCodeReport]

 This takes a few minutes to run and generates an html table of all of the figures in PML along with links to the images and source files. PML must not have any syntax errors, (i.e. it must be compilable) and all figures in the book must be added using the \add*fig(s) macros, (otherwise the numbering gets thrown off). Missing source files are also recorded, and the above pmlMissingCodeReport is also called. All files are packed up into a new directory structure.