Avoid expansion of sys.argv keyword argument in Sphinx documentation

Question

I have a class like this one

import sys

class ACommand(object):

    @classmethod
    def cmd(cls, argv=sys.argv):
        " Executes the command. "
        pass

When documenting this with Sphinx it expands sys.argv to its current value, producing something like the following signature

classmethod cmd(argv=['/path/to/sphinx-build', '-b', 'html', '-d', '_build/doctrees', '.', '_build/html'])

I find it more convenient to have sys.argv in the documentation than its expansion. How can I achieve this?

The problem is that sphinx imports your modules/functions to generate documentation, so it actually _cannot_ see that the argument is really `sys.argv` it simply sees the _value_ that `sys.argv` had when the module was imported. I'm not a Sphinx expert, but maybe there is some way to overwrite this kind of result specifying the value in the docstring(like `:param argv: Arguments ... (default: sys.argv)`) — Bakuriu, Oct 02 '12 at 12:42
@Bakuriu: it is not possible to override the function signature by changing the docstring. See http://stackoverflow.com/a/12087750/407651. — mzjn, Oct 02 '12 at 18:13
@mzjn: That's why I said _maybe_. Anyway I think that such a feature would be useful. reST already provides `:param ...:` and `:type ...:`, so it probably wont be that hard to include it in the system. You simply have to first get the signature of the function, then read the docstring and eventually overwrite the signature with the new information. — Bakuriu, Oct 02 '12 at 18:28
@Bakuriu: I retract my comment from Oct 2. You *can* override the function signature by changing the docstring. See http://stackoverflow.com/a/12087750/407651. — mzjn, Nov 07 '12 at 17:52

score 0 · Accepted Answer · answered Oct 02 '12 at 10:22

0

You could create a proxy object such as

class ListProxy(object):
    def __init__(self, l):
        self.list = l
    def __getitem__(self, i):
        return self.list[i]

and then

@classmethod
def cmd(cls, argv=ListProxy(sys.argv)):
    " Executes the command. "

Or, easier, you could do

@classmethod
def cmd(cls, argv=None):
    " Executes the command. "
    if argv is None:
        argv = sys.argv

answered Oct 02 '12 at 10:22

glglgl

1 Answers1