[Python-Dev] cpython: Adding unittest.mock documentation (original) (raw)

Michael Foord fuzzyman at voidspace.org.uk
Mon Mar 26 22:32:26 CEST 2012

On 26 Mar 2012, at 08:11, Georg Brandl wrote:

On 26.03.2012 00:13, michael.foord wrote:

http://hg.python.org/cpython/rev/adc1fc2dc872 changeset: 75938:adc1fc2dc872 user: Michael Foord <michael at voidspace.org.uk> date: Sun Mar 25 23:12:55 2012 +0100 summary: Adding unittest.mock documentation

files: Doc/library/development.rst | 6 + Doc/library/unittest.mock-examples.rst | 887 +++++++++ Doc/library/unittest.mock-getting-started.rst | 419 ++++ Doc/library/unittest.mock-helpers.rst | 537 +++++ Doc/library/unittest.mock-magicmethods.rst | 226 ++ Doc/library/unittest.mock-patch.rst | 538 +++++ Doc/library/unittest.mock.rst | 900 ++++++++++ Lib/unittest/mock.py | 8 +- 8 files changed, 3516 insertions(+), 5 deletions(-) That seems a bit much splitting to me.

Ok, it's just the style of the current mock documentation. My original intention was to create one big-ass api doc more in keeping with the current library doc styles.

(By the way, the ".. module::" directive should only be in one place.)

Thanks. Maybe sphinx could complain about duplicates.

I would organize the mock, mock-patch, mock-magicmethods and mock-helpers as one file in Doc/library, and put the other two in Doc/howto, just as for logging.

The examples pages aren't written in a howto style - there's a getting started guide (basic examples) and then a bunch of separate more advanced examples illustrating specific features of unittest.mock or particular mocking scenarios.

I'll move the api documentation into a single doc and the getting started guide and examples as a second page.

In general, I wouldn't mind splitting off more of the exemplary material from the main library docs, putting it in the howto section.

Hmmm... in general I think I'd like to see the documentation for non-trivial modules include some examples (separate from - and after - the api docs) . Hiving them off as a howto makes them harder to find. More in depth howto guides in addition to this are a good thing though.

Michael

Georg

Python-Dev mailing list Python-Dev at python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk

-- http://www.voidspace.org.uk/

May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html

More information about the Python-Dev mailing list