Writing a Tutorial

If you want to contribute a Chapter to the Tutorial, please follow the following steps.

Step 1: Come up with a Title and Chapter Number

Every Tutorial has a chapter number and some memorable name. For example: "8. Some Advanced Topic". Note: If your topic is advanced, it should probably go after already existing chapters.

Step 2: Create the Directory Structure

Every Tutorial Chapter must live in CARLSIM_ROOT/doc/source/tutorial. In that directory, create a subdirectory with the chapter number and title you came up with in Step 1. For example, "8. Some Advanced Topic" could translate to "8_some_advanced_topic". Don't make the directory name too long or use special chars. Separate words with underscores and use only lower-case letters.

Within that directory, create the following subdirectories and files:

• doc/
• results/
• scripts/
• Makefile
• main_{name of the Makefile target}.cpp

doc/ should contain a single file for your Doxygen markup, call it "tutorial{chapter number}.dox". If you want to put figures in your Chapter, put them here, too.

results/ should contain only a single file ".readme" that is included so that git will add the (otherwise empty) directory. Direct all CARLsim output to this directory.

scripts/ should contain any MATLAB scripts (e.g. for the Offline Analysis Toolbox). Every Tutorial should come with a "initOAT.m" and a "demoOAT.m". Feel free to add to the "demoOAT.m" file.

All directories and files other than doc/ are concerned with running the C++ code that accompanies the Tutorial. Cut-and-paste a Makefile and a .cpp from another Tutorial. Rename the .cpp file to main_{name of the Makefile target}.cpp. Make all necessary changes to the Makefile to compile the code.

Don't forget to git add all your files and directories.

Step 3: Edit CARLsimLayout.xml

In order for your new Tutorial Chapter to appear in the HTML pages, we need to create an entry in the navigation pane. Open CARLsimLayout.xml and find the code block that reads

<tab type="usergroup" visible="yes" title="Tutorial">
...
</tab>

In there is a list of all existing Tutorial Chapters. Add yours, for example:

<tab type="usergroup" visible="yes" title="8. Some Advanced Topic" url="@ref tut8_some_advanced_topic"/>

You will have to put the referrer "tut8_some_advanced_topic" in your Doxygen file, so make it concise.

Step 4: Edit CARLsim.config.doxy

In order for the new Doxygen files and references to be found, we need to tell CARLsim.config.doxy. Find the line that assigns the variable INPUT:

INPUT                  = ../carlsim/interface/include \
...

Add the doc/ folder to the list, for example:

                         source/tutorial/8_some_advanced_topic/doc

Do the same for the variable IMAGE_PATH, otherwise your figures will not be found.

Step 5: Write the Tutorial

Now write the Tutorial following the regular Doxygen rules.

Every Tutorial chapter should start with the same introduction, listing:

1. What the tutorial is trying to do (e.g. trying to construct a network with Gabor receptive fields that give orientation-selective cells)
2. What the user will know at the end of the tutorial (e.g. how to implement a custom ConnectionGenerator, how to raster-plot activity)
3. What the tutorial assumes the user already knows (e.g., C++, how to use SpikeMonitor)

For inspiration, you can have a look at the Brian Tutorials.