Skip to content

Commit

Permalink
ENH: Add automatically generated CLI module documentation
Browse files Browse the repository at this point in the history 
Switch to MyST markdown parser (https://myst-parser.readthedocs.io/) from recommonmark for two reasons:
1. Sphinx has deprecated recommonmark and recommends MyST now. See readthedocs/recommonmark#221.
2. MyST allows accessing all reStructuredText features with markdown syntax! This is truly amazing, because we can use the simple and intuitive markdown syntax that everyone knows and still access all rst features. It adds essential features that are missing from markdown, such as including other markdown (or rST) files, linking to subsections, etc.

Generate CLI module documentation from module descriptor XML files automatically, during documentation setup. Generating the documentation for all modules takes a few seconds. The generated markdown file can be included in a manually created markdown file, which makes it easy to add custom content and cross-reference content from other documentation pages. Limitation: extension that are bundled with Slicer are currently documented in Slicer repository, while it would be preferable to pull documentation from the extension's repository (see Slicer#5669).

Move all documentation from rst to markdown:
- this makes the entire documentation use a single markup syntax and the same that is used in the forum, wiki, readme files, etc.
- code often become corrupted when added to the script repository because rST required adding indentation, which - depending on text editor settings - messed up indentation of Python code
- GitHub can preview markdown formatting

Co-authored-by: Jean-Christophe Fillion-Robin <[email protected]>
  • Loading branch information
@lassoan @jcfr
lassoan and jcfr committed Jun 1, 2021
1 parent 7cce89a commit b82b68f
Show file tree
Hide file tree
Showing 162 changed files with 7,579 additions and 6,562 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,4 @@ tags

# Documentation
Docs/_build
Docs/_moduledescriptions
3 changes: 3 additions & 0 deletions AUTHORS.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Credits

Please see the GitHub project page at <https://github.com/Slicer/Slicer/graphs/contributors>.
5 changes: 0 additions & 5 deletions AUTHORS.rst
View file

This file was deleted.

44 changes: 44 additions & 0 deletions Docs/_extracli/BRAINSDWICleanup.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
<?xml version="1.0" encoding="utf-8"?>
<executable>
<category>Diffusion.Utilities</category>
<title>BRAINSDWICleanup</title>

<description>Remove bad gradients/volumes from DWI NRRD file.</description>
<acknowledgements></acknowledgements>
<version>5.4.0</version>
<documentation-url></documentation-url>
<license>https://www.nitrc.org/svn/brains/BuildScripts/trunk/License.txt</license>
<contributor>This tool was developed by Kent Williams.</contributor>


<parameters>
<label>Input Parameters</label>
<description></description>

<image type="diffusion-weighted">
<name>inputVolume</name>
<flag>i</flag>
<longflag>inputVolume</longflag>
<description>Required: input image is a 4D NRRD image.</description>
<label>Input Image Volume</label>
<channel>input</channel>
</image>
<image type="diffusion-weighted">
<name>outputVolume</name>
<flag>o</flag>
<longflag>outputVolume</longflag>
<description>given a list of </description>
<label>NRRD File with bad gradients removed.</label>
<channel>output</channel>
<default></default>
</image>
<integer-vector>
<name>badGradients</name>
<longflag>badGradients</longflag>
<flag>b</flag>
<default></default>
<label>list of bad gradient volumes</label>
</integer-vector>
</parameters>

</executable>
188 changes: 188 additions & 0 deletions Docs/_extracli/BRAINSDeface.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,188 @@
<?xml version="1.0" encoding="utf-8"?>
<executable>
<category>Utilities.BRAINS</category>
<title>Brain Deface from T1/T2 image (BRAINS)</title>
<description>
This program: 1) will deface images from a set of images. Inputs must be ACPC aligned, and AC, PC, LE, RE provided.
</description>
<version>5.4.0</version>
<documentation-url></documentation-url>
<license>https://www.nitrc.org/svn/brains/BuildScripts/trunk/License.txt</license>
<contributor>
This tool is created by Hans J. Johnson.
</contributor>
<acknowledgements>
This work was developed by the University of Iowa Department of Electrical and Computer Engineering.
</acknowledgements>

<parameters>
<label>Input Images</label>
<description>First Image, Second Image and Mask Image</description>

<file fileExtensions=".fcsv">
<name>inputLandmarks</name>
<flag>l</flag>
<longflag>inputLandmarks</longflag>
<description>Input Landmark File with LE, and RE points defined in physical locations</description>
<label>Landmarks File</label>
<default></default>
<channel>input</channel>
</file>

<image multiple="true">>
<name>inputVolume</name>
<flag>i</flag>
<longflag>inputVolume</longflag>
<description>Input images, all images must be in the exact same physical space, ACPC aligned and consistent with landmarks.</description>
<label>Source Reference Image</label>
<channel>input</channel>
</image>
<image multiple="true">>
<name>passiveVolume</name>
<flag>p</flag>
<longflag>passiveVolume</longflag>
<description>Input images not used in generating masks, all images must be in the exact same physical space as inputVolumes, ACPC aligned and consistent with landmarks.</description>
<label>Source Passive Images Image</label>
<channel>input</channel>
</image>


<image>
<name>inputMask</name>
<longflag>inputMask</longflag>
<description>Optional pre-generated mask to use.</description>
<label>Optional Mask</label>
<channel>input</channel>
</image>

<string-enumeration>
<name>defaceMode</name>
<longflag>defaceMode</longflag>
<element>zero</element>
<element>blur</element>
<default>blur</default>
</string-enumeration>
</parameters>

<parameters>
<label>Output Files</label>
<description>Outputs from both MUSH generation and brain volume mask creation</description>

<image fileExtensions=".nii.gz,.nrrd" type="label">
<name>outputMask</name>
<flag>o</flag>
<longflag>outputMask</longflag>
<description>The brain volume mask generated from the MUSH image</description>
<label>brain volume mask</label>
<channel>output</channel>
<default>output.nii.gz</default>
</image>
<directory>
<name>outputDirectory</name>
<flag>d</flag>
<longflag>outputDirectory</longflag>
<description>The output directory to writing the defaced input files</description>
<label>OutputDirectory</label>
<channel>output</channel>
<default>/tmp</default>
</directory>
</parameters>

<parameters>
<label>Run Mode</label>
<description>Modify the program to only generate a mask</description>

<boolean>
<name>noMaskApplication</name>
<longflag>noMaskApplication</longflag>
<description>Do not apply the mask to the input images used to generate the mask</description>
<label>No Mask Application</label>
<!-- The default for boolean parameters is always set to false.-->
</boolean>
</parameters>

<parameters>
<label>Output Image Intensity Normalization</label>
<description>Parameters for normalizing the output images.</description>
<double>
<name>upperPercentile</name>
<longflag>upperPercentile</longflag>
<description>Upper Intensity Percentile (0.99 default)</description>
<label>Upper Percentile</label>
<default>0.99</default>
<constraints>
<minimum>0.0</minimum>
<maximum>1.0</maximum>
<step>.001</step>
</constraints>
</double>

<double>
<name>lowerPercentile</name>
<longflag>lowerPercentile</longflag>
<description>Lower Intensity Percentile (0.01 default)</description>
<label>Lower Percentile</label>
<default>0.01</default>
<constraints>
<minimum>0.0</minimum>
<maximum>1.0</maximum>
<step>.001</step>
</constraints>
</double>

<double>
<name>upperOutputIntensity</name>
<longflag>upperOutputIntensity</longflag>
<description>Upper Output Intensity</description>
<label>Upper Output Intensity</label>
<default>255</default>
<constraints>
<minimum>0</minimum>
<maximum>255</maximum>
<step>.1</step>
</constraints>
</double>

<double>
<name>lowerOutputIntensity</name>
<longflag>lowerOutputIntensity</longflag>
<description>Lower Output Intensity</description>
<label>Lower Output Intensity</label>
<default>0</default>
<constraints>
<minimum>0</minimum>
<maximum>255</maximum>
<step>.1</step>
</constraints>
</double>

<boolean>
<name>no_clip</name>
<longflag>no_clip</longflag>
<description>Do not clip Values outside of this range to be the "Outside Value"</description>
<label>Upper Output Intensity</label>
<!-- The default for boolean parameters is always set to false.-->
</boolean>

<boolean>
<name>no_relative</name>
<longflag>no_relative</longflag>
<description>Do not scale to the relative percentiles of the output scale</description>
<label>Relative Scaling</label>
<!-- The default for boolean parameters is always set to false.-->
</boolean>

<integer>
<name>debugLevel</name>
<longflag>debugLevel</longflag>
<description>Level of Debugging (0=None)</description>
<label>Debug Level</label>
<default>0</default>
<constraints>
<minimum>0</minimum>
<maximum>10</maximum>
<step>1</step>
</constraints>
</integer>
</parameters>
</executable>
Loading

0 comments on commit b82b68f

Please sign in to comment.