search

InsightSoftwareConsortium / ITK

Insight Toolkit (ITK) -- Official Repository. ITK builds on a proven, spatially-oriented architecture for processing, segmentation, and registration of scientific images in two, three, or more dimensions.
https://itk.org
Apache License 2.0
1.4k stars 664 forks source link

Standardize documentation in `Utilities` scripts #796

Open jhlegarreta opened 5 years ago

jhlegarreta commented 5 years ago

Description

The Utilities and Utilities/Maintenance folders contain a number of scripts that are important both to ease a number of tasks related to the toolkit and to keep the toolkit healthy.

However, many of the lack a proper documentation. There is some truth in that only a limited number of people (mainly maintainers) use them effectively, but even then, it may be worthwhile properly documenting them.

If they followed some standard, the documentation could be rendered on a web page, much like the Doxygen class documentation, and thus the purpose and use of the scripts would be accessible. That would allow for a more effective information hand-off to new maintainers, or other community members could be aware of such scripts to apply them in some parts of the toolkit (e.g. remotes, third parties, etc.).

Expected information

Proper/canonical script documentation (both header-like comment and usage help message, following some documentation standard if possible, e.g.:

https://stackoverflow.com/questions/14008125/shell-script-common-template https://unix.stackexchange.com/questions/6891/how-can-i-add-man-page-entries-for-my-own-power-tools

having some mandatory sections/fields:

and formatting.

With a result that could look like: https://linux.die.net/man/7/groff_man

If this is something that could be automated, it would be nice. Otherwise, it will need to be done manually.

Also, if this is made effective, the ITK Software Guide will need to contain a section dedicated to documenting how the bash scripts and their usage needs to be ideally written (#!/bin/bash lines, copyright notice, arguments, if named or required, etc.) and documented (script header, script usage, etc.).

Actual information

Maintenance scripts lacking proper documentation and/or no standards followed to document scripts.

Versions

master.

If the commit number is required, run $ git rev-parse --short HEAD. -->

Additional Information

None.

jhlegarreta commented 5 years ago

A few good candidates to start with/test on are:

They are nicely documented, so they would ease the task of getting a working version, and show the way for the rest of the scripts.