Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Standardize documentation in `Utilities` scripts #796

Open
jhlegarreta opened this issue May 1, 2019 · 1 comment

Comments

Projects
None yet
1 participant
@jhlegarreta
Copy link
Member

commented May 1, 2019

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:

  • NAME
  • SYNOPSIS
  • DESCRIPTION
  • OPTIONS
  • IMPLEMENTATION
  • EXAMPLES
  • SEE ALSO

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

This comment has been minimized.

Copy link
Member Author

commented May 2, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.