AHM2012-Slicer-Documentation

Where ?

• Wiki [1]
• Doxygen [2]

How to write end user documentation for your module

• See Documentation/4.0/Modules/YOURMODULENAME

Source code naming and documentation style

• See HowTo

CMake documentation

• Similarly to what's done in CTK, all Slicer CMake macro will be documented. See CTK API

Documenting a module

• Examples:
  • Modules/Core/Cameras/Documentation/Cameras/{xml, dox}
  • Modules/Loadable/Models/Documentation/Models.{xml, dox}
  • Modules/Scripted/Scripts/Endoscopy.{xml, dox}
  • Modules/CLI/Add/Add.xml
• One location to specify description, contributors, ...

• Modules/Core/Cameras/Documentation/Cameras.xml:

<?xml version="1.0" encoding="utf-8"?>
<executable>
 <category>Developer Tools</category>
 <title>Cameras</title>
 <description><![CDATA[
<p>Bring core support for multiple cameras and 3D views in Slicer.</p>
<p>The multi views and cameras framework is available from the "Camera" modules. This module displays two pull-down menus. The first one, "View", lists all available views and lets the user create new 3D views. The second one, "Camera", lists all available cameras, and lets the user create new cameras.</p>
<p>Only one camera is used by a view at a time. When a view is selected from the pull-down, the camera it is currently using is automatically selected in the second pull-down.</p>
<dl>
<dt>Create a new camera.</dt>
<dd>In the "Camera" pull-down menu, select "Create New Camera": a new camera node is created (most likely named "Camera1", as opposed to the default "Camera" node), and automatically assigned to the currently selected view node (named "View" by default). Try interacting with the 3D view.</dd>
<dt>Assign a camera to a view.</dt>
<dd>Select any camera node from the "Camera" pull-down menu: the camera is assigned to the currently selected view. For example, try selecting back the "Camera" node if you have created a "Camera1" node in the previous step, and you should notice the 3D view on the right update itself to reflect the different point of view. Note: a camera can not be shared between two views: selecting a camera already used by a view will effectively swap the cameras between the two views.</dd>
<dt>Create a new view</dt>
<dd>Select the "Tabbed 3D Layout" from the layout button in the toolbar. In the "View" pull-down menu, select "Create New View": a new view node is created (most likely named "View1", as opposed to the default "View" node), and displayed on the right under a new tab. You can select which view to display by clicking on the corresponding tab in the "Tabbed 3D Layout". Interacting in that view will automatically mark it as "active"; there can only be one "active" view at a time in Slicer, and it always feature a thin dark blue border. Since a view can not exist without a camera, a new camera node is automatically created and assigned to this new view (most likely named "Camera2" if you have created "Camera1" in the previous steps). At this point, you can assign any of the previously created cameras to this new view (say, the "Camera" or "Camera1" nodes).</dd>
</dl>
]]>
 </description>
 <version>4.0</version>
 <documentation-url>http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/Cameras</documentation-url>
 <license>slicer4</license>
 <contributor>Julien Finet, Kitware, Sebastien Barre, Kitware Inc.</contributor>
 <acknowledgements>This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149.
 </acknowledgements>
 <parameters>
  <label>Cameras</label>
  <description>List the 3D views and cameras in the scene.</description>
  <parameter>
   <label>View</label>
   <description>Select a 3D view. "View" is the main 3D view, additional 3D views are named "View_1", "View_2" etc. On selection, the view active camera is automatically selected in the Camera pull-down.</description>
  </parameter>
  <parameter>
   <label>Camera</label>
   <description>Active camera of the current view.</description>
  </parameter>
 </parameters>
</executable>

• Modules/Core/Cameras/Documentation/Cameras.dox:

/**
\defgroup Slicer_QtModules_Cameras Cameras
\ingroup Slicer_QtModules
This module manages 3D views and cameras nodes.

*/

What's next ?

• Update Slicer wiki
• Automatic versioning of Wiki documentation. Create Documentation/4.2 using Documentation/4.0
• Package wiki documentation within Slicer
• Any suggestions ?