Difference between revisions of "Documentation/4.1/HowTo"

From Slicer Wiki
Jump to: navigation, search
(Prepend documentation/versioncheck template. See http://na-mic.org/Mantis/view.php?id=2887)
 
(30 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
<noinclude>{{documentation/versioncheck}}</noinclude>
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
 
{{documentation/{{documentation/version}}/header}}
 
{{documentation/{{documentation/version}}/header}}
Line 8: Line 9:
 
|abovestyle  =  
 
|abovestyle  =  
  
−
|image        = [[File:3DSlicer4Logo-H-218X144.png|218px|alt=3D Slicer {{documentation/version}}]]
+
|image        = [[File:3DSlicer41Logo-H-218X144.png|218px|alt=3D Slicer {{documentation/version}}]]
 
|imagestyle  =  
 
|imagestyle  =  
 
|headerstyle  = background:#E7DCC3;
 
|headerstyle  = background:#E7DCC3;
Line 38: Line 39:
 
This document aims at describing the principle and guidelines to consider when writing Slicer user documentation.
 
This document aims at describing the principle and guidelines to consider when writing Slicer user documentation.
  
−
The {{documentation/version}} documentation framework has been redesigned keeping in mind the following principles:
+
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.
 
* 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.
 
* Smart use of mediawiki templates to enforce consistency and reduce maintenance work.
 +
 +
 +
__TOC__
  
 
= Naming conventions =
 
= Naming conventions =
 
# The application '''Slicer''' should be referenced with an uppercase '''S'''.
 
# The application '''Slicer''' should be referenced with an uppercase '''S'''.
 
# All documentation should be added as subpages under '''Documentation/X.Y/''' where '''X''' and '''Y''' are respectively the '''major''' and '''minor''' Slicer version.
 
# All documentation should be added as subpages under '''Documentation/X.Y/''' where '''X''' and '''Y''' are respectively the '''major''' and '''minor''' Slicer version.
−
# Version of Slicer should NOT be written in plain text, [[Template:Documentation/version|documentation/version]] template should be used instead.
+
# Version of Slicer should NOT be written in plain text, {{[[Template:Documentation/version|documentation/version]]}} template should be used instead.
 
# [[Documentation/{{documentation/version}}/SlicerApplication]] should be the root of all subpages specific to Slicer application.
 
# [[Documentation/{{documentation/version}}/SlicerApplication]] should be the root of all subpages specific to Slicer application.
 
# [[Documentation/{{documentation/version}}/Modules]] should be the root of all subpages specific to Slicer modules.
 
# [[Documentation/{{documentation/version}}/Modules]] should be the root of all subpages specific to Slicer modules.
−
# 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.0/Modules/Foo'''
+
# 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/{{documentation/version}}/Modules/Foo'''
 
# Collaborator names, logos or URLs should be referenced using the convenient [[Template:Collaborator|Collaborator]] template.
 
# Collaborator names, logos or URLs should be referenced using the convenient [[Template:Collaborator|Collaborator]] template.
 +
## For example: <nowiki>''{{collaborator|longname|namic}}''</nowiki> generates ''{{collaborator|longname|namic}}''
 +
# Email addresses must be wrapped with the '''<nowiki><email></email></nowiki>''' tags
  
 
= Category =
 
= Category =
Line 56: Line 62:
  
 
= SlicerApplication page =
 
= SlicerApplication page =
−
# [[Template:Documentation/4.0/slicerapplication-header|slicerapplication-header]] and [[Template:Documentation/4.0/slicerapplication-footer|slicerapplication-footer]] templates should be respectively used at the top and the bottom of the page.
+
# [[Template:Documentation/{{documentation/version}}/slicerapplication-header|slicerapplication-header]] and [[Template:Documentation/{{documentation/version}}/slicerapplication-footer|slicerapplication-footer]] templates should be respectively used at the top and the bottom of the page.
  
 
= Module page =
 
= Module page =
Line 63: Line 69:
 
# Base your work on either [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME]] or an [[:Category:Documentation/{{documentation/version}}/Modules|existing module]] documentation.
 
# Base your work on either [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME]] or an [[:Category:Documentation/{{documentation/version}}/Modules|existing module]] documentation.
 
# For CLI modules, the '''SVNREVISION''' revision number is reported on this [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Applications/CLI page]. The module description and the information for developers would be automatically extracted from the corresponding XML description.  
 
# For CLI modules, the '''SVNREVISION''' revision number is reported on this [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Applications/CLI page]. The module description and the information for developers would be automatically extracted from the corresponding XML description.  
−
{{note}} For the moment it's required to update that number at multiple location within the wiki source of a given module documentation page. Soon this will be centralized.
 
 
# See [[Documentation/{{documentation/version}}/ModulesMetadata|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.
 
# See [[Documentation/{{documentation/version}}/ModulesMetadata|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 ==
 
== 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.
 
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.
Line 71: Line 77:
 
# Copy the content of the [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|template]] module and paste it in a page you created with the name of your module: [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME]].
 
# Copy the content of the [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|template]] module and paste it in a page you created with the name of your module: [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME]].
 
# Edit the wiki code to replace the generic information with the module specific information. You can upload screenshots and tutorials.
 
# 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 ==
 
== 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.
 
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.
Line 76: Line 83:
 
## create a ''Documentation'' subdirectory in your module directory (e.g. ''Slicer4/Modules/Loadable/Transforms/Documentation'').
 
## create a ''Documentation'' subdirectory in your module directory (e.g. ''Slicer4/Modules/Loadable/Transforms/Documentation'').
 
## Copy and rename the ''YourModuleName.{xml,dox}'' files from an existing module documentation.
 
## Copy and rename the ''YourModuleName.{xml,dox}'' files from an existing module documentation.
−
# Add description for each [[Documentation/{{documentation/version}}/Developers/Style_Guide/UI#Section|section]] in your module (''YourModuleName.xml'') applying the following pattern:
+
# Add description for each [[Documentation/{{documentation/version}}/Developers/Style_Guide/UI#Section|section]] of your module (''YourModuleName.xml'') applying the following pattern:
 
<pre>
 
<pre>
 
   <parameters>
 
   <parameters>
Line 100: Line 107:
 
== Documentation for a scripted module ==
 
== 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.
 
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.
−
== Documentation for an extension ==
+
 
−
#Create a regular wiki page for each module of the extension using the [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|template]] page. The URLs of the extension modules are the same than the core modules.
+
= Extension page =
−
# Add an extension entry in [[Documentation/{{documentation/version}}/Extensions]]
+
# Create a [[#Module_page|regular wiki page]] for each module of the extension using the [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|template]] page. The URLs of the extension modules are the same than the built-in modules.
−
# Edit [[Documentation/{{documentation/version}}]] to make sure your extension is listed.
+
# Create an extension page
 +
## [[Template:Documentation/{{documentation/version}}/extension-footer|extension-footer]] template should be at the bottom of the page.
 +
## If the extension bundles exactly [[Documentation/{{documentation/version}}/Developers/Tutorials/BundleModulesIntoExtension#Extension_bundles_1_module|one]] module, use [{{fullurl:Documentation/{{documentation/version}}/Extensions/SkullStripper|redirect=no}} this template]
 +
## If the extension bundles [[Documentation/{{documentation/version}}/Developers/Tutorials/BundleModulesIntoExtension#Extension_bundles_N_modules|more]] than one module, use [[Documentation/{{documentation/version}}/Extensions/Plastimatch|this template]].
 +
# Add an extension entry in [[Documentation/{{documentation/version}}/Extensions#Extension_Categories]]
 +
# The extension should now be listed on [[Documentation/{{documentation/version}}]].
  
 
= Miscellaneous =
 
= Miscellaneous =
 
* High resolution logos are in the [[Logo_Gallery|Logo Gallery]]
 
* High resolution logos are in the [[Logo_Gallery|Logo Gallery]]
−
* The list of collaborators with the official name, icon and url is located in the [[Template:Collaborator|collaborator template]] page.
+
* There is a python helper script for SEM compliant tools that can save a significant amount of transcription time:  Slicer/Utilities/Scripts/SEMToMediaWiki.py  
−
* There is a python helper script for SEM compliant tools that can save a significant amount of transcription time:  Slicer/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

Latest revision as of 07:27, 14 June 2013

Home < Documentation < 4.1 < HowTo


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



3D Slicer
3D Slicer 4.1
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.1
License Contribution and Software License Agreement
v · d · e

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.1/SlicerApplication should be the root of all subpages specific to Slicer application.
  5. Documentation/4.1/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.1/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

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.1/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.1/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.1/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 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.
  2. Create an extension page
    1. extension-footer template should be at the bottom of the page.
    2. If the extension bundles exactly one module, use this template
    3. If the extension bundles more than one module, use this template.
  3. Add an extension entry in Documentation/4.1/Extensions#Extension_Categories
  4. The extension should now be listed on Documentation/4.1.

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
Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/4.1/HowTo&oldid=32320"