docstring

I'd like to reference a previously-documented function parameter elsewhere in a Python docstring. Consider the following (admittedly completely artificial) example: def foo(bar): """Perform foo action :param bar: The bar parameter """ def nested(): """Some nested function that depends on enclosing scope's bar parameter. I'd like to reference function foo's bar parameter here with a link, is that possible?""" return bar * bar # ... return nested() Is there a simple way to embed a parameter reference using Sphinx markup, or will this happen automagically? (I'm a complete Sphinx newbie. I've been

What is the preferred way to write Python doc string? """ or " In the book Dive Into Python , the author provides the following example: def buildConnectionString(params): """Build a connection string from a dictionary of parameters. Returns string.""" In another chapter , the author provides another example: def stripnulls(data): "strip whitespace and nulls" return data.replace("\00", "").strip() Both syntax work. The only difference to me is that """ allows us to write multi-line doc. Is there any difference other than that? From the PEP8 Style Guide : PEP 257 describes good docstring

I have a Python script with a docstring. When the parsing of the command-line arguments does not succeed, I want to print the docstring for the user's information. Is there any way to do this? Minimal example #!/usr/bin/env python """ Usage: script.py This describes the script. """ import sys if len(sys.argv) < 2: print("<here comes the docstring>") The docstring is stored in the module's __doc__ global. print(__doc__) By the way, this goes for any module: import sys; print(sys.__doc__) . Docstrings of functions and classes are also in their __doc__ attribute. Here is an alternative that does

What, in Your opinion is a meaningful docstring? What do You expect to be described there? For example, consider this Python class's __init__ : def __init__(self, name, value, displayName=None, matchingRule="strict"): """ name - field name value - field value displayName - nice display name, if empty will be set to field name matchingRule - I have no idea what this does, set to strict by default """ Do you find this meaningful? Post Your good/bad examples for all to know (and a general answer so it can be accepted). I agree with "Anything that you can't tell from the method's signature". It

Is there an option to print the output of help('myfun'). The behaviour I'm seeing is that output is printed to std.out and the script waits for user input (i.e. type 'q' to continue). There must be a setting to set this to just dump docstrings. Alternatively, if I could just dump the docstring PLUS the "def f(args):" line that would be fine too. Searching for "python help function" is comical. :) Maybe I'm missing some nice pydoc page somewhere out there that explains it all? To get exactly the help that's printed by help(str) into the variable strhelp : import pydoc strhelp = pydoc.render_doc