Documenting Python scripts for non-programmers

Question

We are currently looking for ways to help the non-programming members of the sysadmin group familiarize themselves with Python scripts used for day-to-day sysadmin tasks.

Does anyone have any suggested documentation tools or best practices that we might find useful for this purpose?

Edit to address S.Lott's comment:

First, my apologies for being too brief on my initial question. My primary goal is to make sure that someone, even a non-programmer, is easily able to troubleshoot my scripts if I'm not in that day or if I leave the organization.

What I'm looking for is practices used by other people who have the "script coder" role in a technical group such as a sysadmin team. For example, before I begin the process of scripting a task, I've gotten into the habit of first writing an article in our shared wiki explaining each step in detail. I then base my Python scripts on the article--using it as pseudo code.

Other examples of the sorts of things I'm looking for:

• Using tools such as Sphinx to provide easily available doc

• Having group discussions to go over code before putting in production

• Allowing group members to first go over the process manually (we usually go this route but perhaps we should make it a more common practice)

Or, just as valuable if not more so, negatives such as:

• Found that heavy commenting is a waste of time because the logic flow is still foreign to non-programmers

• Lean toward using pexpect because of the verbosity lost when using high level modules

The above are just examples of things I thought of. Hope this clarifies the question! As always, thanks SO'ers.

Answer 1

There is a book on this subject - "Python for Unix and Linux System Administration".

• http://oreilly.com/catalog/9780596515829

And an article on developer works which might provide you the flavor that you may want to follow.

• http://www.ibm.com/developerworks/aix/library/au-python/

And almost any one, irrespective of how, he is going to apply it, would want to work on the basics of the language itself. There is a good starter on web apart from tutorial that is distributed along with standard python distribution.

• http://diveintopython.org/

Answer 2

I find that using argparse as the basis for script invocation parsing/routing tends to produce a decent first line of documentation. If used as intended, your sysadmins can run some_script --help to get a description of the script's purpose and a summary of its options.

It can be fairly trivial to link the documentation sources used by the parser building code to the actual docstrings of functions and classes in your code and that of the script itself. It depends on the complexity of the script, but this can often be a low-effort way to get sufficient documentation.