Take the 2-minute tour ×

Is there any way I can use Sphinx to document the command line inputs of a python script? I am able to document inputs of functions or methods but I don't know how to document inputs of scripts. I have been trying to follow the same syntax I use for functions by adding in the source file the line .. automodule:: scriptLDOnServer where scriptLDOnServer is my python script (which corresponds to my main).

The problem is that I get an error like this:

File "/home/ubuntu/SVNBioinfo/trunk/Code/LD/scriptLDOnServer.py", line 10, in <module>
IndexError: list index out of range

It seems that Sphinx is trying to get the command line inputs but in my source file there are no inputs so the import fails. Is there a way to solve this? Should I use another command in the source for a script instead of a module?

Sorry for not being very clear but it is difficult to explain the problem.

share|improve this question

1 Answer 1

up vote 1 down vote accepted

It is failing while you are importing the file because you are trying to access sys.argv[7] at import time. This is not something you should be doing. Such code which can possibly fail should be either in an if __name__ == '__main__': block or in a function, so that it won't be executed when the code is imported.

This holds generally. You should never* write code which will fail to import or which has any side-effects of being imported.

* Conditions apply. But you'd better have pretty good justification before breaking this rule.

share|improve this answer
Thanks for your answer, I was not aware that the main function had to be enclosed in those tags –  Rossella May 8 '12 at 9:48
Another situation demonstrating why importing should be safe is help('modules'); it goes and finds everything that can be imported and imports it. If you've got something that causes a crash or exit (a few do - it's universally a bug) it breaks it. –  Chris Morgan May 8 '12 at 10:22
That makes sense, thanks for making me aware of this issue –  Rossella May 9 '12 at 1:42
How can i comment input parameters for a module, I tried using the same syntax used for functions (:param name_parameter:) but it does not seem to recognize it for module input parameters(argv). What is the best way of documenting these parameters? –  Rossella May 9 '12 at 10:16
@Rossella: your module should not be depending on sys.argv unless it is an entry-point. If it is, use command-line program markup. –  Chris Morgan May 9 '12 at 12:59

Your Answer


