Ezio Melotti added the comment: Daniel, I would suggest you to start with a basic example that gives an idea about how to use the module and its main functionalities. If necessary you could add a section at the bottom with more examples. You can also show how a method works with a short snippet (2-3 lines) just after the documentation of the method, but this doesn't mean that every method should have one. If you have lot of examples you might consider doing a separate tutorial/howto. As a reference see the examples in http://docs.python.org/py3k/library/html.parser.html and http://docs.python.org/py3k/library/unittest.html#basic-example. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________