Difference between revisions of "Documentation/Description"

From Slicer Wiki
Jump to: navigation, search
m (Text replacement - "https?:\/\/wiki.slicer.org\/slicerWiki\/index.php\/([^ ]+) " to "https://www.slicer.org/wiki/$1")
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Slicer4:Developers| Back to Slicer 4 developers page]]
 
 
 
=Naming convention=
 
=Naming convention=
 
*For matter of consistency, both page have been renamed:
 
*For matter of consistency, both page have been renamed:
**Module:EndUserDocumentationTemplate-Documentation-4.0 -> Documentation/4.0/Modules/YOURMODULENAME
+
**Module:EndUserDocumentationTemplate-Documentation-4.0 -> '''Documentation/4.0/Modules/YOURMODULENAME'''
 
**Modules:GradientAnisotropicFilter-Documentation-4.0 -> Documentation/4.0/Modules/GradientAnisotropicDiffusion
 
**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"
 
*The main documentation page has also been renamed from "Documentation-4.0" to "Documentation/4.0"
*All module documentation page for a given version of Slicer Y.Z should be named according to the following pattern: Documentation/X.Y/Modules/MODULENAME
+
*All module documentation page for a given version of Slicer Y.Z should be named according to the following pattern: '''Documentation/X.Y/Modules/MODULENAME'''
 
 
  
 
=Category=
 
=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 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 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
+
*The following page will list all element from the given category: https://www.slicer.org/wiki/Category:Documentation-4.0-Modules*"category" is a parameter of the "module-footer" template.
*"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].
 
*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:
 
*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:
Line 74: Line 70:
 
=Documentation packaging in Slicer=
 
=Documentation packaging in Slicer=
 
*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" 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.
**See http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-section
+
**See https://www.slicer.org/wiki/Template:Documentation/4.0/module-section =Critical details=
 
 
=Critical details=
 
 
*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.
 
*If a name is incorrect, it should be fixed/updated at the source ! Not just in the documentation.
Line 88: Line 82:
 
   
 
   
 
* Please, review both the template [1] and GradientAnisotropicDiffusion [2] documentation and let me know what you think.
 
* Please, review both the template [1] and GradientAnisotropicDiffusion [2] documentation and let me know what you think.
**[1] http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/YOURMODULENAME
+
**[1] https://www.slicer.org/wiki/Documentation/4.0/Modules/YOURMODULENAME**[2] https://www.slicer.org/wiki/Documentation/4.0/Modules/GradientAnisotropicDiffusion**[3] http://wiki.slicer.org/slicerWiki/index.php?title=Template:Documentation/4.0/module-footer&action=edit
**[2] http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.0/Modules/GradientAnisotropicDiffusion
+
**[4] https://www.slicer.org/wiki/Template:Documentation/4.0/module-cli-category**[5] http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules/Filtering
**[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
 
**[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] https://www.slicer.org/wiki/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] https://www.slicer.org/wiki/Template:Documentation/4.0/module-developerinfo**[11] http://www.mediawiki.org/wiki/Extension:EmailObfuscator
**[11] http://www.mediawiki.org/wiki/Extension:EmailObfuscator
 
 
**[12] http://www.mediawiki.org/wiki/Extension:EmailAddressImage
 
**[12] http://www.mediawiki.org/wiki/Extension:EmailAddressImage
 
**[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

Latest revision as of 14:54, 27 November 2019

Home < Documentation < Description

Naming convention

  • For matter of consistency, both page 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 page 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: https://www.slicer.org/wiki/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 "documentation/version". **See [7]
    • In other word, assuming the current page is "Documentation/4.2" adding Description 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

Developer information

  • 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.
  • 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, 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

  • 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" 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.
  • 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 inspire 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]
  • Setup a mechanism so that current "Documentation Set" follow Slicer source trunk could be duplicated and "frozen"
  • Implement "developerinfo"