search

FactoryBoy / factory_boy

A test fixtures replacement for Python
https://factoryboy.readthedocs.io/
MIT License
3.48k stars 392 forks source link

Documentation is hard to understand #380

Open mark0978 opened 7 years ago

mark0978 commented 7 years ago 
classmethod _after_postgeneration(cls, obj, create, results=None)
Parameters: 
obj (object) – The object just generated
create (bool) – Whether the object was ‘built’ or ‘created’
results (dict) – Map of post-generation declaration name to call result
The _after_postgeneration() is called once post-generation declarations have been handled.

Its arguments allow to handle specifically some post-generation return values, for instance.

The circular loop in some of the docs makes it very hard to know how to customize factory boy. I'm sure in your mind it is all crystal clear and easily understood, but this kind of documentation just doesn't help.

I think part of the problem is I've never seen a good pipe line of factory boy model generation anywhere. so know what postgeneration is and after_postgeneration is really doesn't make sense to me.

Maybe I'm just stupid, or maybe the docs need to assume less of the reader.

rbarrois commented 7 years ago

@mark0978 That's a good point; great docs are very hard to write.

A good starting point from us would be an example of what you'd consider "good documentation" for these features: should we add more context? provide an example project? a howto section?

mark0978 commented 7 years ago

How about the overview of these two pages. Where they backup a few setps from the code to give the feel of what is going on? https://docs.djangoproject.com/en/1.11/topics/http/views/ https://docs.djangoproject.com/en/1.11/topics/http/middleware/

By trial and error I have managed to get some more advanced things to work, but it really involved stepping thru the code in a debugger vs knowing what to expect and being able to write to that. There are some things that I'm not sure I have found the "right" way of doing it, but they work for me, so that is enough.

rbarrois commented 7 years ago

@mark0978 I've started work on this topic in a dedicated branch; would you mind providing some feedback on that? https://github.com/FactoryBoy/factory_boy/blob/cb92aa4d582f9a22a5e40ed757d203b35b6605c0/docs/walkthrough.rst

Thanks!

mark0978 commented 7 years ago

Wow! That is a GREAT start! I think you have the idea. BRAVO!!!!

The one triad of models that gave me the most grief was

Where multiple users could be part of a single account, but an account can't exist without at least one user. And a User can have multiple accounts (but only one "primary" account)

And then lots of things are linked via Foreign keys to either a User or an Account. And some things are linked to both, so you know which Account the object belongs to and which User within the account operated on that object .

The biggest complication comes from users with multiple accounts and accounts with multiple users :-)

On Mon, Jul 31, 2017 at 7:15 PM, Raphaël Barrois notifications@github.com wrote:

@mark0978 https://github.com/mark0978 I've started work on this topic in a dedicated branch; would you mind providing some feedback on that? https://github.com/FactoryBoy/factory_boy/blob/ cb92aa4d582f9a22a5e40ed757d203b35b6605c0/docs/walkthrough.rst

Thanks!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/FactoryBoy/factory_boy/issues/380#issuecomment-319231929, or mute the thread https://github.com/notifications/unsubscribe-auth/AAGeptLmxE-8hgjxG75WnMCFgCQSbG3jks5sTm4pgaJpZM4NKYMt .