Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I have a couple of Python modules that are meant to be run as scripts. How should I write the docstrings at the module and function level to make it clear how to run and use the module?

share|improve this question
    
Are these scripts run by users manually or automatically as part of some process? Who is the intended user? –  Thomas Owens Aug 24 '11 at 15:30
    
One of the scripts is run as part of a cron job, but all of them have to be usable by users. –  murgatroid99 Aug 24 '11 at 15:38

3 Answers 3

I'd mimick a man(1) page

NAME
      this command does things
SYNOPSIS
      command do-things nice
DESCRIPTION
      things are nice when this command does them
share|improve this answer

Personally I use the docstrings for other programmers/installers, there I document the purpose and any setup details that you need to look at rarely. For user documentation, I use the argparse module so users can run: program --help

import argparse

# other stuff

parser = argparse.ArgumentParser(
    description='Path building utility.',
    epilog="""Default operation is to read a list of directory
           names from stdin and print a semi-colon delimited
           path list to stdout.  To terminate --add, --append,
           --prepend or --remove list, use -- as in: {}
           --remove *foo* *bar* -- input.file
           """.format(os.path.basename(sys.argv[0])))
parser.add_argument('--add', '--prepend', 
    help='add specified directories to the front of the path', 
    dest='front', type=str, nargs='+', metavar='DIR', action='append')

# etc.
share|improve this answer
    
This looks like a good idea, but at the moment my scripts have few enough options that it would probably add some unnecessary complexity. –  murgatroid99 Aug 24 '11 at 16:30

In addition to ZJR's suggestion of mimicking a man page, you can also provide a usage statement, return codes, and in-code documentation.

I would consider providing a usage statement that explains how to invoke the application in a clear, concise manner. This would simply provide a list of the arguments, what the arguments represent, if a given argument is optional, and any other relevant information. This would be convenient to users who invoke your scripts from the command-line.

For automated applications that call your scripts, I would consider using various return codes to document errors or other non-standard execution considerations. These can be easily parsed and would shift handling of exceptional cases (especially those that you simply can't handle in your script) as well as logging of the event into the calling application.

Using docstrings might be overkill, depending on the complexity of the script, but some form of in-code documentation is needed for future developers (including youself in the future). I would include a high-level overview of what the script does as the very first thing in the file. Self-documenting code would always help, as well, so make sure you've got good variable names. If there's any complex logic, make sure it's clear what's going on and why you made the design decisions that you did with comments.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.