Difference between revisions of "2011 Slicer4-Documentation-Sprint"
m (Text replacement - "http://www.slicer.org/slicerWiki/index.php/" to "https://www.slicer.org/wiki/") |
|||
(26 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 | + | *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 | + | * 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 104: | Line 154: | ||
==ToDo== | ==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 | |
− | + | * <del>Add "EmailObfuscator"[11] or "EmailAddressImage"[12] extension to mediawiki that will be used inside the "contact" template [13]</del> '''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. | |
− | |||
− | |||
− | |||
− | |||
− | Please, review both the template [1] and GradientAnisotropicDiffusion [2] documentation | ||
− | |||
==Links== | ==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 | [11] http://www.mediawiki.org/wiki/Extension:EmailObfuscator | ||
Line 143: | 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-SprintContents
- 1 What
- 2 Who
- 3 Where
- 4 When
- 5 Background
- 6 Participants
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
- For matter of consistency, both example pages have been renamed:
- Module:EndUserDocumentationTemplate-Documentation-4.0 -> Documentation/4.0/Modules/YOURMODULENAME
- Modules:GradientAnisotropicFilter-Documentation-4.0 -> Documentation/4.0/Modules/GradientAnisotropicDiffusion
- The main documentation page has also been renamed from "Documentation-4.0" to 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
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
- This could be done with the help of a few convenient custom templates:
- It allows to tune / update how the documentation looks like for a given documentation set.
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
- 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.
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
[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
[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
- Ron Kikinis
- Steve Pieper
- Julien Finet
- Jean-Christophe Fillion-Robin
- Nicole Aucoin