Documentation/4.8/Developers/Tutorials/DocumentModule

For the latest Slicer documentation, visit the read-the-docs.

3D Slicer
Description
Research platform for the analysis and visualization of medical images, including image guided therapy.
Free and extensible open source package.
Multi-platform	Linux, MacOSX, Windows
Version	4.8
License	Contribution and Software License Agreement

Overview

This document aims at describing the principle and guidelines to consider when writing Slicer user documentation.

The documentation framework has been designed keeping in mind the following principles:

• Single location for editing documentation (either the wiki or the source code), no duplicative editing.
• Smart use of mediawiki templates to enforce consistency and reduce maintenance work.

Naming conventions

1. The application Slicer should be referenced with an uppercase S.
2. All documentation should be added as subpages under Documentation/X.Y/ where X and Y are respectively the major and minor Slicer version.
3. Version of Slicer should NOT be written in plain text, {{documentation/version}} template should be used instead.
4. Documentation/4.8/SlicerApplication should be the root of all subpages specific to Slicer application.
5. Documentation/4.8/Modules should be the root of all subpages specific to Slicer modules.
6. Module subpage should be named after the module name used in the associated source repository. Assuming the module is named Foo, the corresponding subpage is expected to be Documentation/4.8/Modules/Foo
7. Collaborator names, logos or URLs should be referenced using the convenient Collaborator template.
   1. For example: ''{{collaborator|longname|namic}}'' generates National Alliance for Medical Image Computing (NA-MIC)
8. Email addresses must be wrapped with the <email></email> tags

Documentation version

In addition to the wiki documentation specific to each release 4.0, 4.1 ... there is also a namespace named "Nightly".

See https://www.slicer.org/wiki/Documentation/Nightly * This set of documentation pages applies to the nightly build of Slicer.

• Documentation associated with new features, new modules, new extensions etc .. should be added into the Nightly set.

• If an edit done on Nightly pages also applies to the "4.10" ones, the edit should also be done on the 4.10 pages.

• When Slicer 4.12 will be released, the set of "Nightly" pages will be copied into "4.12" then the nightly pages will continue to evolve until the next release.

See email sent on the list August 23, 2012.

Category

1. All subpages should be categorized. See [1]
2. The user documentation pages are grouped in the Slicer Application and Modules categories.

SlicerApplication page

1. slicerapplication-header and slicerapplication-footer templates should be respectively used at the top and the bottom of the page.

Module page

1. module-header and module-footer templates should be respectively used at the top and the bottom of the page.
2. modulename should be used instead of writing in plain text the name of the module.
3. Base your work on either Documentation/4.8/Modules/YOURMODULENAME or an existing module documentation.
4. For CLI modules, the SVNREVISION revision number is reported on this page. The module description and the information for developers would be automatically extracted from the corresponding XML description.
5. See this page to define the revision number. The revision number associated to a module is used to extract module information from the source code directly.

Documentation for a CLI module

The main idea is to re-use the documentation of the CLI parameters in the wiki. When a CLI is added into Slicer, please execute the following steps to create the module online documentation.

1. Create a CLI in Slicer4/Modules/CLI
2. Add your module in Documentation/4.8/ModulesMetadata. Adding a module consists of adding a module name+revision pair alphabetically in the list. The revision number must correspond to the most up to date revision number of your module.
3. Copy the content of the template module and paste it in a page you created with the name of your module: Documentation/4.8/Modules/YOURMODULENAME.
4. Edit the wiki code to replace the generic information with the module specific information. You can upload screenshots and tutorials.

Documentation for a loadable module

Creating online documentation for loadable modules is similar to CLI modules. The difference is that loadable modules don't have parameter descriptions, it must be added separately.

1. In Slicer4, if it doesn't exist yet
   1. create a Documentation subdirectory in your module directory (e.g. Slicer4/Modules/Loadable/Transforms/Documentation).
   2. Copy and rename the YourModuleName.{xml,dox} files from an existing module documentation.
2. Add description for each section of your module (YourModuleName.xml) applying the following pattern:

  <parameters>
    <label>Section1 header</label>
    <parameter>
      <label>Parameter1 name</label>
      <description><![CDATA[Parameter1 description]]></description>
    </parameter>
  </parameters>
  <parameters>
    <label>Section2 header</label>
    <parameter>
      <label>Parameter2 name</label>
      <description><![CDATA[Parameter2 description]]></description>
    </parameter>
    <parameter>
      <label>Parameter3 name</label>
      <description><![CDATA[Parameter3 description]]></description>
    </parameter>
  ...

Documentation for a scripted module

The trick used in loadable module documentation is not supported yet for scripted modules. Documentation must be written directly in the created module wiki page.

Extension page

1. Create an extension page
   1. extension-footer template should be at the bottom of the page. Except for page doing a REDIRECT.
   2. If the extension bundles exactly one module, use this template
   3. If the extension bundles more than one module, use this template.
2. Add an extension entry in Documentation/4.8/Extensions#Extension_Categories
3. The extension should now be listed on Documentation/4.8.
4. Create a regular wiki page for each module of the extension using the template page. The URLs of the extension modules are the same than the built-in modules.

Remarks

Actively maintained and developed extension

• If the extension is actively developed and maintained so that the code of the nightly extension is the same as the extension associated with a specific slicer release (i.e 4.10), a different approach could be considered.

Extension bundles ONE module

• In addition to create the following pages:

Documentation/Nightly/Extensions/YOURMODULENAME
Documentation/4.10/Extensions/YOURMODULENAME
Documentation/Nightly/Modules/YOURMODULENAME
Documentation/4.10/Modules/YOURMODULENAME

• ... and setup the following redirect:

Documentation/Nightly/Extensions/YOURMODULENAME  ->   Documentation/Nightly/Modules/YOURMODULENAME

Documentation/4.10/Modules/YOURMODULENAME  ->   Documentation/Nightly/Modules/YOURMODULENAME

Documentation/4.10/Extensions/YOURMODULENAME  ->   Documentation/Nightly/Modules/YOURMODULENAME   # Since double redirect are not supported. Version specific extension page redirects to Nightly module page.

• The only page that would be updated would be the Nightly one:

Documentation/Nightly/Modules/YOURMODULENAME

Extension bundles N modules

In addition to create the following pages:

Documentation/Nightly/Modules/YOURMODULENAME_0
Documentation/Nightly/Modules/YOURMODULENAME_1
[...]
Documentation/Nightly/Modules/YOURMODULENAME_N

Documentation/Nightly/Extensions/YOUREXTENSIONNAME

Documentation/4.10/Modules/YOURMODULENAME_0
Documentation/4.10/Modules/YOURMODULENAME_1
[...]
Documentation/4.10/Modules/YOURMODULENAME_N

Documentation/4.10/Extensions/YOUREXTENSIONNAME

• ... and setup the following redirect:

Documentation/4.10/Modules/YOURMODULENAME_0 -> Documentation/Nightly/Modules/YOURMODULENAME_0
Documentation/4.10/Modules/YOURMODULENAME_1 -> Documentation/Nightly/Modules/YOURMODULENAME_1
[...]
Documentation/4.10/Modules/YOURMODULENAME_N -> Documentation/Nightly/Modules/YOURMODULENAME_N

Documentation/4.10/Extensions/YOUREXTENSIONNAME -> Documentation/Nightly/Extensions/YOUREXTENSIONNAME

• The only page(s) that would be updated would be the Nightly ones:

Documentation/Nightly/Modules/YOURMODULENAME_0
Documentation/Nightly/Modules/YOURMODULENAME_1
[...]
Documentation/Nightly/Modules/YOURMODULENAME_N

Documentation/Nightly/Extensions/YOUREXTENSIONNAME

Case where a version specific documentation page diverges from the Nightly one

• If for some reason the documentation associated with the version specific extension is going to diverge from the Nightly one. Before modifying the Nightly page, *MAKE SURE* to create the associated version-ed page(s) by copying the content of the Nighty module page(s) into their own page(s).

Miscellaneous

• High resolution logos are in the Logo Gallery
• There is a python helper script for SEM compliant tools that can save a significant amount of transcription time: Slicer/Utilities/Scripts/SEMToMediaWiki.py
  • To use it run "python Slicer/Utilities/Scripts/SEMToMediaWiki.py -x XMLFILE.xml -o OUTPUT.txt" and the mediawiki content will be in OUTPUT.txt

Developer FAQ: Writing Documentation

How to reference module or extension documentation hosted on the Slicer wiki ?

The URL including the Nightly namespace should be used.

Good: https://www.slicer.org/wiki/Documentation/Nightly/Modules/GaussianBlurImageFilter Poor: https://www.slicer.org/wiki/Documentation/4.4/Modules/GaussianBlurImageFilter References to documentation hosted on the wiki usually occurs when:

• writing module or extension description
• setting the documentation URL in CMakeLists.txt, cpp or python source files.

Rational: This will facilitate maintenance and avoid to update source files after each release.