[Python-Dev] cpython: Adding unittest.mock documentation

[Michael Foord]

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