Difference between revisions of "Documentation/4.0/HowTo"

From Slicer Wiki
Jump to: navigation, search
(Prepend documentation/versioncheck template. See http://na-mic.org/Mantis/view.php?id=2887)
 
(25 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
<noinclude>{{documentation/versioncheck}}</noinclude>
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
−
{{documentation/{{documentation/version}}/module-header}}
+
{{documentation/{{documentation/version}}/header}}
 
<!-- ---------------------------- -->
 
<!-- ---------------------------- -->
−
 
−
 
−
This is a placeholder for guidelines on how to insert documentation into Slicer 4 source code. JC and Jim will edit this page as part of their discussions.
 
  
 
{{Infobox
 
{{Infobox
Line 11: Line 9:
 
|abovestyle  =  
 
|abovestyle  =  
  
−
|image        = [[File:Logo-3DSlicer.png|200px|alt=3D Slicer {{documentation/version}}]]
+
|image        = [[File:3DSlicer4Logo-H-218X144.png|218px|alt=3D Slicer {{documentation/version}}]]
 
|imagestyle  =  
 
|imagestyle  =  
 
|headerstyle  = background:#E7DCC3;
 
|headerstyle  = background:#E7DCC3;
Line 37: Line 35:
 
}}
 
}}
  
 +
= Overview =
 +
 +
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:
 +
* 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 =
 +
# 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, [[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}}/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'''
 +
# Collaborator names, logos or URLs should be referenced using the convenient [[Template:Collaborator|Collaborator]] template.
 +
 +
= Category =
 +
# All subpages should be categorized. See [https://secure.wikimedia.org/wikipedia/mediawiki/wiki/Help:Categories#Adding_a_page_to_a_category]
 +
# The user documentation pages are grouped in the [[:Category:Documentation/{{documentation/version}}/SlicerApplication|Slicer Application]] and [[:Category:Documentation/{{documentation/version}}/Modules|Modules]] categories.
 +
 +
= 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.
  
−
The basic approach is to have most of the documentation in the source code and to populate the wiki pages using scripts.  
+
= Module page =
−
*For the end user documentation use this [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|Template]]
+
# [[Template:Documentation/4.0/module-header|module-header]] and [[Template:Documentation/4.0/module-footer|module-footer]] templates should be respectively used at the top and the bottom of the page.
 +
# [[Template:Documentation/modulename|modulename]] should be used instead of writing in plain text the name of the module.
 +
# 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.
 +
{{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.
  
−
*All module documentation page should be named according to the following pattern: '''Documentation/4.0/Modules/MODULENAME'''
+
= Miscellaneous =
−
*High resolution logos are in the [[Logo_Gallery|Logo Gallery]]
+
* High resolution logos are in the [[Logo_Gallery|Logo Gallery]]
−
*Collaborators' name, logo, URL have been centralized into a convenient set of [http://wiki.slicer.org/slicerWiki/index.php/Template:Collaborator templates]
+
* There is a python helper script for SEM compliant tools that can save a significant amount of transcription time:  Slicer/Scripts/SEMToMediaWiki.py
−
*The following [http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules link] will list all modules belonging to the Documentation/4.0/Modules category.
 
−
*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.
 

Latest revision as of 07:29, 14 June 2013

Home < Documentation < 4.0 < HowTo


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



3D Slicer
3D Slicer 4.0
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.0
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 4.0 documentation framework has been redesigned 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.0/SlicerApplication should be the root of all subpages specific to Slicer application.
  5. Documentation/4.0/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.0/Modules/Foo
  7. Collaborator names, logos or URLs should be referenced using the convenient Collaborator template.

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.0/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.

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.

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