Difference between revisions of "Documentation/Nightly/HowTo"

From Slicer Wiki
Jump to: navigation, search
(→‎SlicerApplication page: not applicable to Slicer5 readthedocs-based documentation)
Tag: 2017 source edit
Line 48: Line 48:
  
 
= 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 ==
+
This section has moved to https://slicer.readthedocs.io/en/latest/developer_guide/extensions.html#documentation
−
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 ==
 
−
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 =

Revision as of 20:20, 8 June 2020

Home < Documentation < Nightly < HowTo


For the latest Slicer documentation, visit the read-the-docs.



3D Slicer
3D Slicer Nightly
Description
Research platform for the analysis and visualization of medical images, including image guided therapy.
Free and extensible open source package.
Multi-platform Linux, MacOSX, Windows
Version Nightly
License Contribution and Software License Agreement
v · d · e

Overview

This document aims at describing the principle and guidelines to consider when writing Slicer user documentation.

The documentation framework has been designed keep keeping in mind the following principles:

  • Keep documentation at the same place as the source code to make it possible to keep the documentation always in sync with the software implementation.
  • Allow anyone to make changes or propose changes to the documentation.
  • Follow common documentation conventions (formats, rendering tools, and services)


Module page

This section has moved to https://slicer.readthedocs.io/en/latest/developer_guide/extensions.html#documentation

Extension page

  1. Create an extension page
    1. extension-footer template should be at the bottom of the page. Except for page doing a REDIRECT.
    2. If the extension bundles exactly one module, use this template
    3. If the extension bundles more than one module, use this template.
  2. Add an extension entry in Documentation/Nightly/Extensions#Extension_Categories
  3. The extension should now be listed on Documentation/Nightly.
  4. Create a regular wiki page for each module of the extension using the template page. The URLs of the extension modules are the same than the built-in modules.


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 (i.e 4.10), a different approach could be considered.

Extension bundles ONE module

  • In addition to create the following pages:
Documentation/Nightly/Extensions/YOURMODULENAME
Documentation/4.10/Extensions/YOURMODULENAME
Documentation/Nightly/Modules/YOURMODULENAME
Documentation/4.10/Modules/YOURMODULENAME

Documentation/Nightly/Extensions/YOURMODULENAME  ->   Documentation/Nightly/Modules/YOURMODULENAME

Documentation/4.10/Modules/YOURMODULENAME  ->   Documentation/Nightly/Modules/YOURMODULENAME

Documentation/4.10/Extensions/YOURMODULENAME  ->   Documentation/Nightly/Modules/YOURMODULENAME   # Since double redirect are not supported. Version specific extension page redirects to Nightly module page.
  • The only page that would be updated would be the Nightly one:
Documentation/Nightly/Modules/YOURMODULENAME


Extension bundles N modules

In addition to create the following pages: 

Documentation/Nightly/Modules/YOURMODULENAME_0
Documentation/Nightly/Modules/YOURMODULENAME_1
[...]
Documentation/Nightly/Modules/YOURMODULENAME_N

Documentation/Nightly/Extensions/YOUREXTENSIONNAME

Documentation/4.10/Modules/YOURMODULENAME_0
Documentation/4.10/Modules/YOURMODULENAME_1
[...]
Documentation/4.10/Modules/YOURMODULENAME_N

Documentation/4.10/Extensions/YOUREXTENSIONNAME

Documentation/4.10/Modules/YOURMODULENAME_0 -> Documentation/Nightly/Modules/YOURMODULENAME_0
Documentation/4.10/Modules/YOURMODULENAME_1 -> Documentation/Nightly/Modules/YOURMODULENAME_1
[...]
Documentation/4.10/Modules/YOURMODULENAME_N -> Documentation/Nightly/Modules/YOURMODULENAME_N

Documentation/4.10/Extensions/YOUREXTENSIONNAME -> Documentation/Nightly/Extensions/YOUREXTENSIONNAME


  • The only page(s) that would be updated would be the Nightly ones:
Documentation/Nightly/Modules/YOURMODULENAME_0
Documentation/Nightly/Modules/YOURMODULENAME_1
[...]
Documentation/Nightly/Modules/YOURMODULENAME_N

Documentation/Nightly/Extensions/YOUREXTENSIONNAME


Case where a version specific documentation page diverges from the Nightly one

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

Miscellaneous

  • High resolution logos are in the 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
Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/Nightly/HowTo&oldid=63290"