search

cta-observatory / ctapipe

Low-level data processing pipeline software for CTAO or similar arrays of Imaging Atmospheric Cherenkov Telescopes
https://ctapipe.readthedocs.org
BSD 3-Clause "New" or "Revised" License
64 stars 268 forks source link

Document Command-Line Tools #1904

Open HealthyPear opened 2 years ago

HealthyPear commented 2 years ago

Please describe the use case that requires this feature.

Right now Command-Line Tools are not documented.

Describe the solution you'd like

By looking how to do this in protopipe (which - for now - has argparse-based CLI scripts, but the principle is the same) I found a possible automatization of this process for traitlets-based Applications which is already possible to use by ctapipe as it already requires the minimum version that supports this feature. See ipython/traitlets#458 (I couldn't find it nicely explained on their documentation...)

Describe alternatives you've considered

In protopipe I have been doing this by copy-pasting the help output, which is of course error-prone, but it's at least something.

kosack commented 2 years ago

This is simliar to the problem that all traitlets-based classes have poor automatic documentation in sphinx (missing the help strings and defaults of each trait). I think it should be possible to fix that and then all Components and Tools would get reasonable documentation. There are already functions in both to generate the help strings and also documented python config files that could be adopted as sphinx functions.