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