Difference between revisions of "Documentation/4.1/HowTo"
From Slicer Wiki
m (→Extension page) |
m (→Miscellaneous) |
||
Line 118: | Line 118: | ||
= Miscellaneous = | = Miscellaneous = | ||
* High resolution logos are in the [[Logo_Gallery|Logo Gallery]] | * High resolution logos are in the [[Logo_Gallery|Logo Gallery]] | ||
− | * There is a python helper script for SEM compliant tools that can save a significant amount of transcription time: Slicer/Scripts/SEMToMediaWiki.py | + | * There is a python helper script for SEM compliant tools that can save a significant amount of transcription time: Slicer/Utilities/Scripts/SEMToMediaWiki.py |
Revision as of 19:19, 21 June 2012
Home < Documentation < 4.1 < HowTo
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.1 |
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.
Contents
Naming conventions
- 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.
- Version of Slicer should NOT be written in plain text, {{documentation/version}} template should be used instead.
- Documentation/4.1/SlicerApplication should be the root of all subpages specific to Slicer application.
- Documentation/4.1/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.1/Modules/Foo
- Collaborator names, logos or URLs should be referenced using the convenient Collaborator template.
- For example: ''{{collaborator|longname|namic}}'' generates National Alliance for Medical Image Computing (NA-MIC)
- Email addresses must be wrapped with the <email></email> tags
Category
- All subpages should be categorized. See [1]
- The user documentation pages are grouped in the Slicer Application and Modules categories.
SlicerApplication page
- slicerapplication-header and slicerapplication-footer templates should be respectively used at the top and the bottom of the page.
Module page
- module-header and module-footer templates should be respectively used at the top and the bottom of the page.
- modulename should be used instead of writing in plain text the name of the module.
- Base your work on either Documentation/4.1/Modules/YOURMODULENAME or an existing module documentation.
- 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.
- 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.
- Create a CLI in Slicer4/Modules/CLI
- 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.
- 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.
- 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.
- In Slicer4, if it doesn't exist yet
- 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.
- 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
- 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.
- Create an extension page
- extension-footer template should be at the bottom of the page.
- If the extension bundles exactly one module, use this template
- If the extension bundles more than one module, use this template.
- Add an extension entry in Documentation/4.1/Extensions#Extension_Categories
- 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