According to PEP 257 the docstring of command line script should be its usage message:
The docstring of a script (a stand-alone program) should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help"). Such a docstring should document the script's function and command line syntax, environment variables, and files. Usage messages can be fairly elaborate (several screens full) and should be sufficient for a new user to use the command properly, as well as a complete quick reference to all options and arguments for the sophisticated user.
And the the docstring shall be the first string as module level, before anything else, to be available as __doc__.
Now, I'm also using docopt as a usage message parser, so I just have to write the doc string, and it's building the command line parser on its own, and that's great.
_("""...""")
What's not that great, is that I can't find a way to mark the docstring as i18nable for gettext, so I can convert it to other languages when given to docopt. At the time being the only solution I got is to make the usage and help messages stay in english, when all the application's other strings are translated!
As the PEP 20 states:
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
What would be the best way to get around the limitation of not being able to mark the docstring as translatable elegantly?
N.B.: here we consider that I'm doing the gettext.install() in the __init__.py module so that _() is present in the builtins before even __doc__ is being parsed.
I finally found the only good solution to parse docstrings:
-D
--docstrings
Extract module, class, method, and function docstrings. These do
not need to be wrapped in _() markers, and in fact cannot be for
Python to consider them docstrings. (See also the -X option).
will extract all docstrings. So the only one that needs to be translated can be translated using:
args = docopt.docopt(_(__doc__))