Difference between revisions of "2011 Slicer4-Documentation-Sprint"

From NAMIC Wiki
Jump to: navigation, search
m (Text replacement - "http://www.slicer.org/slicerWiki/index.php/" to "https://www.slicer.org/wiki/")
 
(31 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
[[image:Screen Shot 2011-10-20 at 9.20.29 AM.png|thumb|right|400px|The meeting in full swing]]
 
=What=
 
=What=
 
Slicer 4 Documentation Sprint. The purpose of this event is to jump start the documentation for Slicer 4 in preparation for the RSNA release.
 
Slicer 4 Documentation Sprint. The purpose of this event is to jump start the documentation for Slicer 4 in preparation for the RSNA release.
Line 10: Line 11:
 
=Background=
 
=Background=
 
JC has been working on a design which is supposed to accomplish two objectives:
 
JC has been working on a design which is supposed to accomplish two objectives:
−
*Single location for editing documentation, no duplicative editing.
+
*Single location for editing documentation (either the wiki or the source code), no duplicative editing.
 
*As much automation as possible
 
*As much automation as possible
 +
==List of Features & Modules==
 +
List of Slicer functionality that we are planning to use at RSNA. All of them should be fully documented and contain proper acknowledgements.
 +
 +
=== Slicer Features ===
 +
 +
* Application Layout (Wendy)
 +
* Menu Items
 +
* Tool Bars (Wendy)
 +
* Slice Viewer (Wendy)
 +
** Mouse/Key Bindings (Steve)
 +
** Pop Up Controllers (J2)
 +
** Linking Behavior (Jim)
 +
** Compare Viewer (Jim)
 +
* 3D Viewer (Wendy)
 +
** Mouse/Key Bindings
 +
** Pop Up Controllers (Wendy)
 +
* Data Probe (Steve)
 +
* Load Data Dialogs
 +
* Save Data Dialog (Wendy)
 +
 +
=== Modules ===
 +
 +
* Data (Julien)
 +
* Welcome to Slicer (Wendy)
 +
* Volumes (Julien)
 +
* [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/Models Models] (Nicole)
 +
* Scene Views (Nicole)
 +
* Annotations (Nicole)
 +
* Volume Rendering (Julien)
 +
* Editor (Steve)
 +
* [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/ModelMaker Model Maker] (Nicole)
 +
* Diffusion Tensor Estimation (Demian)
 +
* Diffusion Tensor Scalar Measurements (Alex)
 +
* Tractography Labelmap Seeding  (Demian)
 +
* Tractography Fiducial Seeding (Demian)
 +
* Tractography Display (Demian)
 +
* Change Tracker (Andrey)
 +
* N4 bias correction (Andrey)
 +
* Crop tool (Andrey)
 +
* DICOM (Steve)
 +
* EMSegmenter
 +
* BRAINSTools (Hans)
 +
 +
 +
Extensions:
 +
* ABC
 +
* Plastimatch
 +
* Skullstripper
 +
 
==Naming conventions==
 
==Naming conventions==
 
*For matter of consistency, both example pages have been renamed:
 
*For matter of consistency, both example pages have been renamed:
−
**Module:EndUserDocumentationTemplate-Documentation-4.0 -> Documentation/4.0/Modules/YOURMODULENAME
+
**Module:EndUserDocumentationTemplate-Documentation-4.0 -> [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/YOURMODULENAME Documentation/4.0/Modules/YOURMODULENAME]
−
**Modules:GradientAnisotropicFilter-Documentation-4.0 -> Documentation/4.0/Modules/GradientAnisotropicDiffusion
+
**Modules:GradientAnisotropicFilter-Documentation-4.0 -> [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/GradientAnisotropicDiffusion Documentation/4.0/Modules/GradientAnisotropicDiffusion]
−
*The main documentation page has also been renamed from "Documentation-4.0" to "Documentation/4.0"
+
*The main documentation page has also been renamed from "Documentation-4.0" to [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0 Documentation/4.0]
 
*All module documentation pages for a given version of Slicer Y.Z should be named according to the following pattern: Documentation/X.Y/Modules/MODULENAME
 
*All module documentation pages for a given version of Slicer Y.Z should be named according to the following pattern: Documentation/X.Y/Modules/MODULENAME
  
Line 34: Line 84:
  
 
* All pages and template associated with version X.Y of Slicer are located under the page prefix: Documentation/X.Y
 
* All pages and template associated with version X.Y of Slicer are located under the page prefix: Documentation/X.Y
−
* From any documentation page or template, doing so allows to easily extract the current version using the template "documentation/version". See [7]
+
* From any documentation page or template, doing so allows to easily extract the current version using the template [http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/version Template:Documentation/version]. See [7]
−
** In other words, assuming the current page is "Documentation/4.2" adding {{documentation/version}} in the source will return 4.2.
+
** In other words, assuming the current page is "Documentation/4.2" adding <tt><nowiki>{{documentation/version}}</nowiki></tt> in the source will return 4.2.
  
 
* Following each release of Slicer, this approach will allow us to:
 
* Following each release of Slicer, this approach will allow us to:
Line 78: Line 128:
 
==Developer information==
 
==Developer information==
  
−
  a) For each module, the list of bugs, associated tests, list of classes, developer notes .. should be automatically collected. This could be achieved with the help of the "module-developerinfo" template.
+
* For each module, the list of bugs, associated tests, list of classes, developer notes etc. should be collected automatically. This could be achieved with the help of the "module-developerinfo" template.
−
 
+
* Every module should include the template "Documentation/X.Y/module-developerinfo". See [10]
−
  b) Every module should include the template "Documentation/X.Y/module-developerinfo". See [10]
+
* As of today, this template is a placeholder/stub. As soon as, functionality will be implemented all module including that template will automatically display the wanted information.
−
 
+
* This implies:
−
  c) As of today, this template is a placeholder/stub. As soon as, functionality will be implemented all module including that template will automatically display the wanted information.
+
** In mantis, bugs should be assigned to a category / tag and product version
−
 
+
** In CDash, tests should be labeled with both the ModuleName and the Slicer version. Then, using the webapi we should be able to obtain the list of tests, coverage, etc ...
−
d) This implies:
+
** Status of the "Ron rules" could be semi-automatically generated: coverage, number of test, amount of documentation, style, ...
−
        -- In mantis, bug should be assigned a category / tag and product version
 
−
        -- In CDash, tests should be labeled with both the ModuleName and the Slicer version. Then, using the webapi we should be able to obtain the list of tests, coverage, etc ...
 
−
        -- Status of the "Ron rules" could be semi-automatically generated: coverage, number of test, amount of documentation, style, ...
 
−
 
 
  
 
==Categorizing==
 
==Categorizing==
  
−
  a) The list of category is currently manually generated. This is not sustainable. Given the new page structure. These lists could be automatically generated.
+
* The list of category is currently manually generated. This is not sustainable. Given the new page structure. These lists could be automatically generated.
−
 
 
−
  b) Mediawiki offers some nice feature to manage category. Let's use them.
 
  
 +
* Mediawiki offers some nice feature to manage category. Let's use them.
  
 
==Documentation packaging in Slicer==
 
==Documentation packaging in Slicer==
  
−
  a) Since a template "module-section" have been introduced, there is now a placeholder that will allow to refine how sections are identified and will ease the integration in a future Slicer Assistant module.
+
* Since a template "module-section" has been introduced, there is now a placeholder that will allow to refine how sections are identified and will ease the integration in a future Slicer Assistant module.
−
 
+
**See http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-section
−
See http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-section
 
−
 
 
  
 
==Critical details==
 
==Critical details==
  
−
    a) A module should be identified consistently in both the source and the documentation. GradientAnisotropicFilter !=  GradientAnisotropicDiffusion
+
* A module should be identified consistently in both the source and the documentation. GradientAnisotropicFilter !=  GradientAnisotropicDiffusion
−
 
+
* If a name is incorrect, it should be fixed/updated at the source ! Not just in the documentation.
−
    b) If a name is incorrect, it should be fixed/updated at the source ! Not just in the documentation.
 
−
 
 
  
 
==ToDo==
 
==ToDo==
  
−
  a) Look at wiki like "http://techbase.kde.org" .. I think we could be inspired from what they did and improve the "user friendliness" of slicer wiki
+
* Look at wiki like "http://techbase.kde.org" .. I think we could be inspired from what they did and improve the "user friendliness" of slicer wiki
−
 
+
* <del>Add "EmailObfuscator"[11] or "EmailAddressImage"[12] extension to mediawiki that will be used inside the "contact" template [13]</del> '''Done''' - EmailAddressImage added
−
  b) Add "EmailObfuscator"[11] or "EmailAddressImage"[12] extension to mediawiki that will be used inside the "contact" template [13]
+
* Setup a mechanism so that current "Documentation Set" follow Slicer source trunk could be duplicated and "frozen"
−
 
+
* Implement "developerinfo"
−
  c) Setup a mechanism so that current "Documentation Set" follow Slicer source trunk could be duplicated and "frozen"
+
* Please, review both the template [1] and GradientAnisotropicDiffusion [2] documentation.
−
 
 
−
  d) Implement "developerinfo"
 
−
 
 
−
 
−
Please, review both the template [1] and GradientAnisotropicDiffusion [2] documentation and let me know what you think.
 
−
 
 
  
 
==Links==
 
==Links==
  
−
[1] http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/YOURMODULENAME
+
[1] http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/YOURMODULENAME
  
−
[2] http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/GradientAnisotropicDiffusion
+
[2] http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/GradientAnisotropicDiffusion
  
−
[3] http://wiki.slicer.org/slicerWiki/index.php?title=Template:Documentation/4.0/module-footer&action=edit
+
[3] http://wiki.slicer.org/slicerWiki/index.php?title=Template:Documentation/4.0/module-footer&action=edit
  
−
[4] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-cli-category
+
[4] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-cli-category
  
−
[5] http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules/Filtering
+
[5] http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules/Filtering
  
−
[6] http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules/Filtering.Denoising
+
[6] http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules/Filtering.Denoising
  
−
[7] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/version
+
[7] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/version
  
−
[8] http://www.mediawiki.org/wiki/Extension:Duplicator
+
[8] http://www.mediawiki.org/wiki/Extension:Duplicator
  
−
[9] http://www.mediawiki.org/wiki/Extension:Multiplicator
+
[9] http://www.mediawiki.org/wiki/Extension:Multiplicator
  
−
[10] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-developerinfo
+
[10] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-developerinfo
  
 
[11] http://www.mediawiki.org/wiki/Extension:EmailObfuscator
 
[11] http://www.mediawiki.org/wiki/Extension:EmailObfuscator
Line 152: Line 187:
  
 
[13] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/contact
 
[13] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/contact
 +
 +
 +
==Logos==
 +
A ready source of logos can be found [https://www.slicer.org/wiki/Logo_Gallery here].
 +
 +
=Participants=
 +
# Ron Kikinis
 +
# Steve Pieper
 +
# Julien Finet
 +
# Jean-Christophe Fillion-Robin
 +
# Nicole Aucoin

Latest revision as of 17:31, 10 July 2017

Home < 2011 Slicer4-Documentation-Sprint
The meeting in full swing

What

Slicer 4 Documentation Sprint. The purpose of this event is to jump start the documentation for Slicer 4 in preparation for the RSNA release.

Who

Module creators

Where

1249 Boylston Street

When

October 20, starting at 8am

Background

JC has been working on a design which is supposed to accomplish two objectives:

  • Single location for editing documentation (either the wiki or the source code), no duplicative editing.
  • As much automation as possible

List of Features & Modules

List of Slicer functionality that we are planning to use at RSNA. All of them should be fully documented and contain proper acknowledgements.

Slicer Features

  • Application Layout (Wendy)
  • Menu Items
  • Tool Bars (Wendy)
  • Slice Viewer (Wendy)
    • Mouse/Key Bindings (Steve)
    • Pop Up Controllers (J2)
    • Linking Behavior (Jim)
    • Compare Viewer (Jim)
  • 3D Viewer (Wendy)
    • Mouse/Key Bindings
    • Pop Up Controllers (Wendy)
  • Data Probe (Steve)
  • Load Data Dialogs
  • Save Data Dialog (Wendy)

Modules

  • Data (Julien)
  • Welcome to Slicer (Wendy)
  • Volumes (Julien)
  • Models (Nicole)
  • Scene Views (Nicole)
  • Annotations (Nicole)
  • Volume Rendering (Julien)
  • Editor (Steve)
  • Model Maker (Nicole)
  • Diffusion Tensor Estimation (Demian)
  • Diffusion Tensor Scalar Measurements (Alex)
  • Tractography Labelmap Seeding (Demian)
  • Tractography Fiducial Seeding (Demian)
  • Tractography Display (Demian)
  • Change Tracker (Andrey)
  • N4 bias correction (Andrey)
  • Crop tool (Andrey)
  • DICOM (Steve)
  • EMSegmenter
  • BRAINSTools (Hans)


Extensions:

  • ABC
  • Plastimatch
  • Skullstripper

Naming conventions

Category

The following link will list all modules belonging to the Documentation/4.0/Modules category: http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules

  • The template "Documentation/4.0/module-footer" takes care of including the documentation page in the appropriate category. See [3]
  • The following page will list all element from the given category: http://wiki.slicer.org/slicerWiki/index.php/Category:Documentation-4.0-Modules
  • "category" is a parameter of the "module-footer" template.
  • For CLI module, as explained on the template itself [1], it's recommended to use the template "Documentation/4.0/module-cli-category" that can extract the category from the XML module description. See [4].
  • Using the provided module category, the module will also be added to the category "Documentation/4.0/Modules/<MainCategory" and "Documentation/4.0/Modules/<MainCategory.SubCategory>". For example:
    • Documentation/4.0/Modules/Filtering see [5]
    • Documentation/4.0/Modules/Filtering.Denoising see [6].
  • Ideally, it would be great if the category associated with loadable module (interactive module) could also be extracted from a unique location. Doing so would avoid to maintain the category attribute both in the source and in the documentation.

Versioning

  • All pages and template associated with version X.Y of Slicer are located under the page prefix: Documentation/X.Y
  • From any documentation page or template, doing so allows to easily extract the current version using the template Template:Documentation/version. See [7]
    • In other words, assuming the current page is "Documentation/4.2" adding {{documentation/version}} in the source will return 4.2.
  • Following each release of Slicer, this approach will allow us to:
    • minimize the work required after a documentation set is duplicated
    • easily reference the different documentation sets
    • automate the duplication of these pages. Let's note that the mediawiki extensions like "Duplicator" [8] or "Multiplicator" [9] could be useful.
  • "Long life" of past documentation will also be ensured. Indeed, each time the documentation will be duplicated, a complete set of category, template and documentation page will be created. You will find below what the list of pages and templates could like after 4.2 is released:
      [...]
      Documentation/4.0/Modules/Add
      Documentation/4.0/Modules/GradientAnisotropicDiffusion
      Documentation/4.0/Modules/Threshold
      Documentation/4.0/Modules/YOURMODULENAME
      [...]
      Documentation/4.2/Modules/Add
      Documentation/4.2/Modules/GradientAnisotropicDiffusion
      Documentation/4.2/Modules/Threshold
      Documentation/4.2/Modules/YOURMODULENAME
      [...]
      Category:Documentation/4.0/Modules
      Category:Documentation/4.0/Modules/Filtering
      Category:Documentation/4.0/Modules/Filtering.Denoising
      [...]
      Category:Documentation/4.2/Modules
      Category:Documentation/4.2/Modules/Filtering
      Category:Documentation/4.2/Modules/Filtering.Denoising
      [...]
      Template:Documentation/4.0/module-cli-description
      Template:Documentation/4.0/module-header
      Template:Documentation/4.0/module-footer
      [...]
      Template:Documentation/4.2/module-cli-description
      Template:Documentation/4.2/module-header
      Template:Documentation/4.2/module-footer

Separation of information and representation

Developer information

  • For each module, the list of bugs, associated tests, list of classes, developer notes etc. should be collected automatically. This could be achieved with the help of the "module-developerinfo" template.
  • Every module should include the template "Documentation/X.Y/module-developerinfo". See [10]
  • As of today, this template is a placeholder/stub. As soon as, functionality will be implemented all module including that template will automatically display the wanted information.
  • This implies:
    • In mantis, bugs should be assigned to a category / tag and product version
    • In CDash, tests should be labeled with both the ModuleName and the Slicer version. Then, using the webapi we should be able to obtain the list of tests, coverage, etc ...
    • Status of the "Ron rules" could be semi-automatically generated: coverage, number of test, amount of documentation, style, ...

Categorizing

  • The list of category is currently manually generated. This is not sustainable. Given the new page structure. These lists could be automatically generated.
  • Mediawiki offers some nice feature to manage category. Let's use them.

Documentation packaging in Slicer

Critical details

  • A module should be identified consistently in both the source and the documentation. GradientAnisotropicFilter != GradientAnisotropicDiffusion
  • If a name is incorrect, it should be fixed/updated at the source ! Not just in the documentation.

ToDo

  • Look at wiki like "http://techbase.kde.org" .. I think we could be inspired from what they did and improve the "user friendliness" of slicer wiki
  • Add "EmailObfuscator"[11] or "EmailAddressImage"[12] extension to mediawiki that will be used inside the "contact" template [13] Done - EmailAddressImage added
  • Setup a mechanism so that current "Documentation Set" follow Slicer source trunk could be duplicated and "frozen"
  • Implement "developerinfo"
  • Please, review both the template [1] and GradientAnisotropicDiffusion [2] documentation.

Links

[1] http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/YOURMODULENAME

[2] http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/GradientAnisotropicDiffusion

[3] http://wiki.slicer.org/slicerWiki/index.php?title=Template:Documentation/4.0/module-footer&action=edit

[4] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-cli-category

[5] http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules/Filtering

[6] http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules/Filtering.Denoising

[7] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/version

[8] http://www.mediawiki.org/wiki/Extension:Duplicator

[9] http://www.mediawiki.org/wiki/Extension:Multiplicator

[10] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-developerinfo

[11] http://www.mediawiki.org/wiki/Extension:EmailObfuscator

[12] http://www.mediawiki.org/wiki/Extension:EmailAddressImage

[13] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/contact


Logos

A ready source of logos can be found here.

Participants

  1. Ron Kikinis
  2. Steve Pieper
  3. Julien Finet
  4. Jean-Christophe Fillion-Robin
  5. Nicole Aucoin
Retrieved from "https://www.na-mic.org/w/index.php?title=2011_Slicer4-Documentation-Sprint&oldid=97244"