Guide on writing tutorial pages - geoscience-community-codes/GISMO GitHub Wiki

NOTE: Tutorials are under development - we just started writing them.

Aim is something like the ObsPy tutorials, which are fairly atomic. Each tutorial could contain:

  • preamble: objectives of this tutorial & commands you will learn to use
  • each tutorial section should have a link to downloadable the code
  • navigation to previous and next topics?
  • link to a longer examples - an actual real workflow to accomplish a useful scientific task

Perhaps the terminology is backwards - examples could be the short usage like ObsPy tutorials, and tutorials could be longer examples. Think about this.

It might be good to embed examples directly within the relevant section of the Tutorials menu, e.g.

"Example 1: Detect swarms in demo database from Redoubt volcano"

Current direction is just to include inside each class (and perhaps each package) a cookbook function which can be "published" to produce an HTML tutorial page, which is then added to the gh-pages branch so it can be linked under the wiki. For example, under the classes/@Catalog directory there is a cookbook method. This m-file is opened within the MATLAB Editor, and published to classes/@Catalog/html. The files from classes/@Catalog/html are then copied to tutorials/Catalog in the gh-pages branch, which (after committing and pushing) is then available at http://geoscience-community-codes.github.io/GISMO/tutorials/Catalog/cookbook.html. The advantage of this approach is that a cookbook is included in each class of GISMO core, and that same cookbook forms the tutorial materials available via the wiki. (Testing is also then reduced to running the cookbook).

Celso's tips:

  • use anchors to make multi-subject pages:

    `[mylink](/geoscience-community-codes/GISMO/wiki/Page#title-of-section)`