|
|
| (12 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| | + | <noinclude>{{documentation/versioncheck}}</noinclude> |
| | <!-- ---------------------------- --> | | <!-- ---------------------------- --> |
| | {{documentation/{{documentation/version}}/header}} | | {{documentation/{{documentation/version}}/header}} |
| Line 33: |
Line 34: |
| | |data6 = [http://www.slicer.org/pages/LicenseText Contribution and Software License Agreement] | | |data6 = [http://www.slicer.org/pages/LicenseText Contribution and Software License Agreement] |
| | }} | | }} |
| − |
| |
| − | = Overview =
| |
| − |
| |
| − | This document aims at describing the principle and guidelines to consider when writing Slicer user documentation.
| |
| − |
| |
| − | The documentation framework has been designed keeping in mind the following principles:
| |
| − | * Single location for editing documentation (either the wiki or the source code), no duplicative editing.
| |
| − | * Smart use of mediawiki templates to enforce consistency and reduce maintenance work.
| |
| − |
| |
| − |
| |
| − | __TOC__
| |
| − |
| |
| − | = Naming conventions =
| |
| − | # The application '''Slicer''' should be referenced with an uppercase '''S'''.
| |
| − | # All documentation should be added as subpages under '''Documentation/X.Y/''' where '''X''' and '''Y''' are respectively the '''major''' and '''minor''' Slicer version.
| |
| − | # Version of Slicer should NOT be written in plain text, {{[[Template:Documentation/version|documentation/version]]}} template should be used instead.
| |
| − | # [[Documentation/{{documentation/version}}/SlicerApplication]] should be the root of all subpages specific to Slicer application.
| |
| − | # [[Documentation/{{documentation/version}}/Modules]] should be the root of all subpages specific to Slicer modules.
| |
| − | # Module subpage should be named after the '''module name''' used in the associated source repository. Assuming the module is named '''Foo''', the corresponding subpage is expected to be '''Documentation/{{documentation/version}}/Modules/Foo'''
| |
| − | # Collaborator names, logos or URLs should be referenced using the convenient [[Template:Collaborator|Collaborator]] template.
| |
| − | ## For example: <nowiki>''{{collaborator|longname|namic}}''</nowiki> generates ''{{collaborator|longname|namic}}''
| |
| − | # Email addresses must be wrapped with the '''<nowiki><email></email></nowiki>''' tags
| |
| − |
| |
| − | = Documentation version =
| |
| − |
| |
| − | In addition to the wiki documentation specific to each release 4.0, 4.1 ... there is also a namespace named "Nightly".
| |
| − |
| |
| − | See http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly
| |
| − |
| |
| − | * This set of documentation pages applies to the nightly build of Slicer.
| |
| − |
| |
| − | * Documentation associated with new features, new modules, new extensions etc .. should be added into the Nightly set.
| |
| − |
| |
| − | * If an edit done on Nightly pages also applies to the "{{documentation/currentversion}}" ones, the edit should also be done on the {{documentation/currentversion}} pages.
| |
| − |
| |
| − | * When Slicer {{documentation/nextversion}} will be released, the set of "Nightly" pages will be copied into "{{documentation/nextversion}}" then the nightly pages will continue to evolve until the next release.
| |
| − |
| |
| − | See [http://slicer-devel.65872.n3.nabble.com/Slicer-wiki-quot-Nightly-quot-documentation-tt4026026.html email sent on the list August 23, 2012].
| |
| − |
| |
| − | = Category =
| |
| − | # All subpages should be categorized. See [https://secure.wikimedia.org/wikipedia/mediawiki/wiki/Help:Categories#Adding_a_page_to_a_category]
| |
| − | # The user documentation pages are grouped in the [[:Category:Documentation/{{documentation/version}}/SlicerApplication|Slicer Application]] and [[:Category:Documentation/{{documentation/version}}/Modules|Modules]] categories.
| |
| − |
| |
| − | = SlicerApplication page =
| |
| − | # [[Template:Documentation/{{documentation/version}}/slicerapplication-header|slicerapplication-header]] and [[Template:Documentation/{{documentation/version}}/slicerapplication-footer|slicerapplication-footer]] templates should be respectively used at the top and the bottom of the page.
| |
| | | | |
| | = Module page = | | = Module page = |
| − | # [[Template:Documentation/{{documentation/version}}/module-header|module-header]] and [[Template:Documentation/{{documentation/version}}/module-footer|module-footer]] templates should be respectively used at the top and the bottom of the page.
| |
| − | # [[Template:Documentation/modulename|modulename]] should be used instead of writing in plain text the name of the module.
| |
| − | # Base your work on either [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME]] or an [[:Category:Documentation/{{documentation/version}}/Modules|existing module]] documentation.
| |
| − | # For CLI modules, the '''SVNREVISION''' revision number is reported on this [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Applications/CLI page]. The module description and the information for developers would be automatically extracted from the corresponding XML description.
| |
| − | # See [[Documentation/{{documentation/version}}/ModulesMetadata|this page]] to define the revision number. The revision number associated to a module is used to extract module information from the source code directly.
| |
| − |
| |
| − | == Documentation for a CLI module ==
| |
| − | The main idea is to re-use the documentation of the CLI parameters in the wiki. When a CLI is added into Slicer, please execute the following steps to create the module online documentation.
| |
| − | # Create a CLI in Slicer4/Modules/CLI
| |
| − | # Add your module in [[Documentation/{{documentation/version}}/ModulesMetadata]]. Adding a module consists of adding a module name+revision pair alphabetically in the list. The revision number must correspond to the most up to date revision number of your module.
| |
| − | # Copy the content of the [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|template]] module and paste it in a page you created with the name of your module: [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME]].
| |
| − | # Edit the wiki code to replace the generic information with the module specific information. You can upload screenshots and tutorials.
| |
| − |
| |
| − | == Documentation for a loadable module ==
| |
| − | Creating online documentation for loadable modules is similar to CLI modules. The difference is that loadable modules don't have parameter descriptions, it must be added separately.
| |
| − | # In Slicer4, if it doesn't exist yet
| |
| − | ## create a ''Documentation'' subdirectory in your module directory (e.g. ''Slicer4/Modules/Loadable/Transforms/Documentation'').
| |
| − | ## Copy and rename the ''YourModuleName.{xml,dox}'' files from an existing module documentation.
| |
| − | # Add description for each [[Documentation/{{documentation/version}}/Developers/Style_Guide/UI#Section|section]] of your module (''YourModuleName.xml'') applying the following pattern:
| |
| − | <pre>
| |
| − | <parameters>
| |
| − | <label>Section1 header</label>
| |
| − | <parameter>
| |
| − | <label>Parameter1 name</label>
| |
| − | <description><![CDATA[Parameter1 description]]></description>
| |
| − | </parameter>
| |
| − | </parameters>
| |
| − | <parameters>
| |
| − | <label>Section2 header</label>
| |
| − | <parameter>
| |
| − | <label>Parameter2 name</label>
| |
| − | <description><![CDATA[Parameter2 description]]></description>
| |
| − | </parameter>
| |
| − | <parameter>
| |
| − | <label>Parameter3 name</label>
| |
| − | <description><![CDATA[Parameter3 description]]></description>
| |
| − | </parameter>
| |
| − | ...
| |
| − | </pre>
| |
| | | | |
| − | == Documentation for a scripted module ==
| + | This section has moved to https://slicer.readthedocs.io/en/latest/developer_guide/extensions.html#documentation |
| − | The trick used in loadable module documentation is not supported yet for scripted modules. Documentation must be written directly in the created module wiki page.
| |
| | | | |
| | = Extension page = | | = Extension page = |
| − | # Create a [[#Module_page|regular wiki page]] for each module of the extension using the [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|template]] page. The URLs of the extension modules are the same than the built-in modules.
| |
| − | # Create an extension page
| |
| − | ## [[Template:Documentation/{{documentation/version}}/extension-footer|extension-footer]] template should be at the bottom of the page. Except for page doing a REDIRECT.
| |
| − | ## If the extension bundles exactly [[Documentation/{{documentation/version}}/Developers/Tutorials/BundleModulesIntoExtension#Extension_bundles_1_module|one]] module, use [{{fullurl:Documentation/{{documentation/version}}/Extensions/SkullStripper|redirect=no}} this template]
| |
| − | ## If the extension bundles [[Documentation/{{documentation/version}}/Developers/Tutorials/BundleModulesIntoExtension#Extension_bundles_N_modules|more]] than one module, use [[Documentation/{{documentation/version}}/Extensions/Plastimatch|this template]].
| |
| − | # Add an extension entry in [[Documentation/{{documentation/version}}/Extensions#Extension_Categories]]
| |
| − | # The extension should now be listed on [[Documentation/{{documentation/version}}]].
| |
| − |
| |
| − |
| |
| − | == Remarks ==
| |
| − |
| |
| − | === Actively maintained and developed extension ===
| |
| − |
| |
| − | * If the extension is actively developed and maintained so that the code of the nightly extension is the same as the extension associated with a specific slicer release, a different approach could be considered.
| |
| − |
| |
| − | In addition to create the extension page itself:
| |
| − |
| |
| − | Documentation/Nightly/Extensions/YOUREXTENSION
| |
| − |
| |
| − | The only page(s) that would be updated would be the module page(s):
| |
| − |
| |
| − | Documentation/Nightly/Modules/YOURMODULENAME
| |
| − |
| |
| − | * Then, a [http://www.mediawiki.org/wiki/Help:Redirects redirect] from your *extension* version specific page to your Nightly extension page would be created. Since [http://www.mediawiki.org/wiki/Help:Redirects#Double_redirects double redirect are NOT supported] in mediawiki, you would NOT have to create a version-ed page for each module.
| |
| − |
| |
| − | * For example, assuming you maintained the extension for both Slicer {{documentation/currentversion}} and the Nightly one, you would have the following pages:
| |
| − |
| |
| − | Documentation/Nightly/Modules/YOURMODULENAME
| |
| − | Documentation/Nightly/Extensions/YOUREXTENSION
| |
| − | Documentation/{{documentation/currentversion}}/Extensions/YOUREXTENSION
| |
| − |
| |
| − | where
| |
| − | Documentation/{{documentation/currentversion}}/Extensions/YOUREXTENSION
| |
| − |
| |
| − | redirect to
| |
| − | Documentation/Nightly/Extensions/YOUREXTENSION
| |
| − |
| |
| − | * If for some reason the documentation associated with the version specific extension is going to diverge from the Nightly one. Before modifying the Nightly page, *MAKE SURE* to create the associated version-ed page(s) by copying the content of the Nighty module page(s) into their own page(s):
| |
| − | Documentation/{{documentation/currentversion}}/Modules/YOURMODULENAME
| |
| − | Documentation/{{documentation/currentversion}}/Extensions/YOUREXTENSION
| |
| | | | |
| − | = Miscellaneous =
| + | This section has moved to https://slicer.readthedocs.io/en/latest/developer_guide/extensions.html#documentation |
| − | * High resolution logos are in the [[Logo_Gallery|Logo Gallery]]
| |
| − | * There is a python helper script for SEM compliant tools that can save a significant amount of transcription time: Slicer/Utilities/Scripts/SEMToMediaWiki.py
| |
| − | **To use it run "python Slicer/Utilities/Scripts/SEMToMediaWiki.py -x XMLFILE.xml -o OUTPUT.txt" and the mediawiki content will be in OUTPUT.txt
| |
