Documentation/Description - Revision history

Grundlett: Text replacement - "https?:\/\/wiki.slicer.org\/slicerWiki\/index.php\/([^ ]+) " to "https://www.slicer.org/wiki/$1"

2019-11-27T14:54:29Z

Text replacement - "https?:\/\/wiki.slicer.org\/slicerWiki\/index.php\/([^ ]+) " to "https://www.slicer.org/wiki/$1"

Grundlett: Text replacement - "https?:\/\/(?:www|wiki)\.slicer\.org\/slicerWiki\/index\.php\/([^ ]+) " to "https://www.slicer.org/wiki/$1 "

2019-11-27T13:18:52Z

Text replacement - "https?:\/\/(?:www|wiki)\.slicer\.org\/slicerWiki\/index\.php\/([^ ]+) " to "https://www.slicer.org/wiki/$1 "

JChris.FillionR at 00:03, 10 April 2012

2012-04-10T00:03:15Z

JChris.FillionR: /* Naming convention */

2012-01-10T14:43:33Z

Naming convention

JChris.FillionR: moved Slicer4:Documentation-Slicer4 to Documentation/Description

2012-01-10T14:42:27Z

moved Slicer4:Documentation-Slicer4 to Documentation/Description

Kikinis: /* Versioning: */

2011-08-25T15:36:09Z

Versioning:

Kikinis at 13:26, 25 August 2011

2011-08-25T13:26:30Z

Kikinis at 13:25, 25 August 2011

2011-08-25T13:25:32Z

Kikinis: Created page with '1) Naming convention: a) For matter of consistency, both page have been renamed: Module:EndUserDocumentationTemplate-Documentation-4.0 -> Documentation/4.0/Modules/YOURMODUL…'

2011-08-25T13:22:34Z

Created page with '1) Naming convention: a) For matter of consistency, both page have been renamed: Module:EndUserDocumentationTemplate-Documentation-4.0 -> Documentation/4.0/Modules/YOURMODUL…'

New page

1) Naming convention:

a) 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

b) The main documentation page has also been renamed from "Documentation-4.0" to "Documentation/4.0"

c) 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

2) 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

a) The template "Documentation/4.0/module-footer" takes care of including the documentation page in the appropriate category. See [3]

b) The following page will list all element from the given category: http://wiki.slicer.org/slicerWiki/index.php/Category:Documentation-4.0-Modules

c) "category" is a parameter of the "module-footer" template.

d) 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].

e) 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].

f) 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.

3) Versioning:

a) All pages and template associated with version X.Y of Slicer are located under the page prefix: Documentation/X.Y

b) 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 {{documentation/version}} in the source will return 4.2.

c) 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.

d) "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

4) Separation of information and representation

a) This could be done with the help of few convenient custom templates:
See http://wiki.slicer.org/slicerWiki/index.php?title=Category:Templates:Documentation/4.0

b) It allow to tune / update how documentation look like for a given documentation set.

5) 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.

b) Every module should include the template "Documentation/X.Y/module-developerinfo". See [10]

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.

d) 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, ...

6) 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.

b) Mediawiki offers some nice feature to manage category. Let's use them.

7) 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.

See http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-section

8) Critical details:

a) A module should be identified consistently in both the source and the documentation. GradientAnisotropicFilter != GradientAnisotropicDiffusion

b) If a name is incorrect, it should be fixed/updated at the source ! Not just in the documentation.

9) ToDo

a) 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

b) Add "EmailObfuscator"[11] or "EmailAddressImage"[12] extension to mediawiki that will be used inside the "contact" template [13]

c) Setup a mechanism so that current "Documentation Set" follow Slicer source trunk could be duplicated and "frozen"

d) Implement "developerinfo"

Please, review both the template [1] and GradientAnisotropicDiffusion [2] documentation and let me know what you think.

Thanks
Jc

[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

@@ Line 9: / Line 9: @@
 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
+*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:
@@ Line 83: / Line 82: @@
 * 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
 **[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
 **[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
 **[12] http://www.mediawiki.org/wiki/Extension:EmailAddressImage
 **[13] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/contact

@@ Line 71: / Line 71: @@
 =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.
-**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=
 *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.

← Older revision		Revision as of 00:03, 10 April 2012
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:

@@ Line 3: / Line 3: @@
 =Naming convention=
 *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
 *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=

@@ Line 21: / Line 21: @@
 =Versioning:=
+*All pages and template associated with version X.Y of Slicer are located under the page prefix: Documentation/X.Y
-   a) 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 {{documentation/version}} in the source will return 4.2.
-   b) From any documentation page or template, doing so allows to easily extract the current version using the template "documentation/version". See [7]
+*Following each release of Slicer, this approach will allow us to:
-   In other word, assuming the current page is "Documentation/4.2" adding {{documentation/version}} in the source will return 4.2.
+**minimize the work required after a documentation set is duplicated
+**easily reference the different documentation sets
-   c) Following each release of Slicer, this approach will allow us to:
+**automate the duplication of these pages. Let's note that the mediawiki extensions like "Duplicator" [8] or "Multiplicator" [9] could be useful.
-         -- minimize the work required after a documentation set is duplicated
+*"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
@@ Line 59: / Line 55: @@
         Template:Documentation/4.2/module-header
         Template:Documentation/4.2/module-footer
-) Separation of information and representation
+=Developer information=
-   a) This could be done with the help of few convenient custom templates:
+=Documentation packaging in Slicer=
-         See http://wiki.slicer.org/slicerWiki/index.php?title=Category:Templates:Documentation/4.0
+*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.
-   b) It allow to tune / update how documentation look like for a given documentation set.
+=ToDo=
-) Developer information
+* 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
-  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.
+**[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
-  b) Every module should include the template "Documentation/X.Y/module-developerinfo". See [10]
+**[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
-  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.
+**[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
- d) This implies:
+**[8] http://www.mediawiki.org/wiki/Extension:Duplicator
-         -- In mantis, bug should be assigned a category / tag and product version
+**[9] http://www.mediawiki.org/wiki/Extension:Multiplicator
-         -- 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 ...
+**[10] http://wiki.slicer.org/slicerWiki/index.php/Template:Documentation/4.0/module-developerinfo
-        -- Status of the "Ron rules" could be semi-automatically generated: coverage, number of test, amount of documentation, style, ...
+**[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

← Older revision	Revision as of 14:42, 10 January 2012
(No difference)

← Older revision		Revision as of 13:26, 25 August 2011
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: