pydoc is useful but it is not referenced from README so how do people know?

[Jonathan Lange]

The document at <http://pypi.python.org/pypi/fixtures> says:

Isolate your code from environmental variables, delete them or set them to a new value.

>>> fixture = fixtures.EnvironmentVariableFixture('HOME')

But it is not at all clear whether that isolates (how?), deletes or sets to a new value. Regardless of which it does, it's unclear how to achieve the other two without looking at the source code.

[Robert Collins (lifeless)]

This is why pydoc says for me;

    class EnvironmentVariableFixture(fixtures.fixture.Fixture)
     | Isolate a specific environment variable.
     |
     | Method resolution order:
     | EnvironmentVariableFixture
     | fixtures.fixture.Fixture
     | __builtin__.object
     |
     | Methods defined here:
     |
     | __init__(self, varname, newvalue=None)
     | Create an EnvironmentVariableFixture.
     |
     | :param varname: the name of the variable to isolate.
     | :param newvalue: A value to set the variable to. If None, the variable
     | will be deleted.
     |
     | During setup the variable will be deleted or assigned the requested
     | value, and this will be restored in cleanUp.
     |

That seems pretty clear to me. Was it unclear? Or did you go from 'README' -> source code without looking at the API docs ?

[Jonathan Lange (jml)]

On Wed, Jul 20, 2011 at 9:20 PM, Robert Collins
<email address hidden> wrote:
...
> That seems pretty clear to me. Was it unclear? Or did you go from 'README' -> source code without looking at the API docs ?
>

The latter. Basically I never use pydoc.

jml

[Robert Collins (lifeless)]

So I don't want README to be pydoc-but-in-a-different-place. How about some text at the top saying pydoc (epydoc etc etc) have detailed usage information for individual facility.

[Jonathan Lange (jml)]

Yeah, that'd be great. If you've got web hosting for the pydoc, it would be good to include a link to it.