[IPython-dev] Documenting the recent editor sync extension

Fernando Perez fperez.net@gmail....
Tue Aug 26 14:28:16 CDT 2008


Hi Vivian,

I was today trying to help someone use your new editor sync tool:

http://bazaar.launchpad.net/%7Eipython-dev/ipython/trunk/annotate/1121?file_id=ipy_synchronize_with-20080612032938-lxufpyi2plzu3mlc-1

and I realized that in the review process, I forgot to ask you for any
kind of top-level documentation and examples.  Could you please add a
top-level docstring describing the intended purpose of the tool, its
main use cases, and a simple example of how to use it?  There should
be also a short paragraph about it in the
docs/source/interactive/extension_api.txt file, so that users who read
the manual can find out about it.

We really need to move to ensuring that *all* new code can be used by
new users by:

- finding its capabilities in the documentation with a high-level view
- finding a module-level docstring that explains the purpose of the tool
- having good function/class-level docstrings that explain the
specific use of each call.

Otherwise we'll be forever answering these questions on the mailing list.

Cheers,

f


More information about the IPython-dev mailing list