New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: time to clean up and extend the SonataAdmin docs #1519

Open
caponica opened this Issue Aug 8, 2013 · 27 comments

Comments

Projects
None yet
@caponica
Contributor

caponica commented Aug 8, 2013

I've discussed this with @rande and @lsmith77 and I'm going to volunteer to take point on bringing the Sonata docs up to date and organising the addition of cookbook recipes to the SonataAdmin documentation. I'm uniquely qualified to do this since I'm new to SonataAdmin and don't know how it works (yet)!

There are three areas that need attention:

  1. ensure that the existing manual is up to date and easy to read
  2. add manual sections for any undocumented basic functionality
  3. add cookbook style "how to" recipes for more complex use-cases

I will post separate issues here on github for each existing manual page that needs attention, each area of functionality that I know needs documentation and each recipe that needs a (volunteer) chef.

How can you help?

Get involved! There are lots of ways to help:

  • If you know a bit about how SonataAdmin works then take on some of the issues posted and try to solve them.
  • If you are new to Sonata and there's something you don't understand or you feel is not documented well, leave a comment below (in this thread). I'll review it and add a related issue if needed.
  • If you have a website or internal wiki that already has some cookbook entries then you're in a great position to squash an issue or two. Either make a formal PR or just send me the text and then get a warm and fuzzy feeling inside for helping the whole community.

If you're not sure how to make a PR, are not a native english speaker or don't know how to write rst docs that is not a problem. And definitely not an excuse ;) Just send me the information in whatever format you can (e.g. a hyperlink, a word doc in broken english, I'll even take a crack at source material in French or Spanish) and I'll do what I can to reformat it into documentation that can be published for the benefit of the whole community. My Twitter handle and a sonata-specific email address are below.

If you want I can mention your handle or company name in the issue with a quick "thank you" (and maybe even tweet a thank you that mentions you) but you won't get a mention in the docs themselves, which are all basically anonymous.

When is this issue closed?

Docs evolve and grow forever, but individual issues are made to be solved and closed. Once we've gone through and brought the existing manual up to date, added key missing documentation for existing features and built a reasonable cookbook it will be time to close this particular issue and celebrate.

Keep your eyes peeled for the individual issues and I look forward to your responses!

Christian
@h4ppydotcom on twitter
sonata-docs á caponica dotcom

@tiagojsag

This comment has been minimized.

Show comment
Hide comment
@tiagojsag

tiagojsag Aug 8, 2013

Contributor

Question: shall we use some way to avoid multiple people working on the same issue/doc?

Contributor

tiagojsag commented Aug 8, 2013

Question: shall we use some way to avoid multiple people working on the same issue/doc?

@rande

This comment has been minimized.

Show comment
Hide comment
@rande

rande Aug 8, 2013

Member

I guess you can reply to an issue with an estimate time to deliver the PR, so other people can take the lead if the user cannot deliver the work.

Member

rande commented Aug 8, 2013

I guess you can reply to an issue with an estimate time to deliver the PR, so other people can take the lead if the user cannot deliver the work.

@caponica

This comment has been minimized.

Show comment
Hide comment
@caponica

caponica Aug 8, 2013

Contributor

Exactly - comment on the PR if you're working on it, but always provide an ETA, preferably a pretty tight one (hours/days not weeks!). If you're going to miss the ETA or cannot complet it just comment again.

Contributor

caponica commented Aug 8, 2013

Exactly - comment on the PR if you're working on it, but always provide an ETA, preferably a pretty tight one (hours/days not weeks!). If you're going to miss the ETA or cannot complet it just comment again.

@wouterj

This comment has been minimized.

Show comment
Hide comment
@wouterj

wouterj Aug 8, 2013

Contributor

If I may add a tip: Don't document all seperate bundles. The SonataAdminBundle contains all logic and it has multiple implementation bundles which implement a certain driver, for instance a PHPCR driver or ORM driver. Both the main SonataAdminBundle and implementation bundles have their own documentation and both explain things different. Moreover, it's confusing which documentation you can use.

I recommend to create one documentation for the SonataAdminBundle and minimalise the other docs too only an installation section.

Also, explain things in steps and add docs about the basic things. From what I remember, I had to look in the source code to find answers to basic questions such as "what does the configureListFields method" and "which options are available for the FormMapping class?".

I wish you many luck with this project and it's a same I'm so busy at the moment.

Contributor

wouterj commented Aug 8, 2013

If I may add a tip: Don't document all seperate bundles. The SonataAdminBundle contains all logic and it has multiple implementation bundles which implement a certain driver, for instance a PHPCR driver or ORM driver. Both the main SonataAdminBundle and implementation bundles have their own documentation and both explain things different. Moreover, it's confusing which documentation you can use.

I recommend to create one documentation for the SonataAdminBundle and minimalise the other docs too only an installation section.

Also, explain things in steps and add docs about the basic things. From what I remember, I had to look in the source code to find answers to basic questions such as "what does the configureListFields method" and "which options are available for the FormMapping class?".

I wish you many luck with this project and it's a same I'm so busy at the moment.

@tiagojsag

This comment has been minimized.

Show comment
Hide comment
@tiagojsag

tiagojsag Aug 8, 2013

Contributor

Correct me if I'm wrong, but do all driver bundles support the same thing? Same form types, etc etc etc? If so, +1 for it, but if not, I'd use your suggestion, but leave big red warning signs on SonataAdmin's docs telling users to also check the driver bundle, pretty much like now, but DRYing up the docs whenever possible and making the driver bundles docs an appendix.

Contributor

tiagojsag commented Aug 8, 2013

Correct me if I'm wrong, but do all driver bundles support the same thing? Same form types, etc etc etc? If so, +1 for it, but if not, I'd use your suggestion, but leave big red warning signs on SonataAdmin's docs telling users to also check the driver bundle, pretty much like now, but DRYing up the docs whenever possible and making the driver bundles docs an appendix.

@sjopet

This comment has been minimized.

Show comment
Hide comment
@sjopet

sjopet Aug 9, 2013

Contributor

Woot, such great news and awesome effort. I wish you the best of luck and will do what I can to help.

Contributor

sjopet commented Aug 9, 2013

Woot, such great news and awesome effort. I wish you the best of luck and will do what I can to help.

@lineke

This comment has been minimized.

Show comment
Hide comment
@lineke

lineke Aug 12, 2013

Awesome, this will certainly help others! I'll look into my blog post ideas and let you know what else I can help with!

lineke commented Aug 12, 2013

Awesome, this will certainly help others! I'll look into my blog post ideas and let you know what else I can help with!

@lineke

This comment has been minimized.

Show comment
Hide comment
@lineke

lineke Aug 12, 2013

Okay, there are some more ideas I had for blogposts that aren't written yet:

  • Adding account selection functionality to your sonata admin
  • Using a custom password hashing mechanism
  • Inline editing of one-to-many relation

These are old ideas and I need to look up how valid they are nowadays and how I did it, but if you can use them, let me know. Also, there is this blog form a friend of mine with two sonataAdmin posts on there: http://php-jotter.blogspot.co.uk/2013/01/override-display-of-sonatacollectiontyp.html and http://php-jotter.blogspot.co.uk/2013/01/display-subset-or-sorted-list-of.html. Maybe that is of any use?

lineke commented Aug 12, 2013

Okay, there are some more ideas I had for blogposts that aren't written yet:

  • Adding account selection functionality to your sonata admin
  • Using a custom password hashing mechanism
  • Inline editing of one-to-many relation

These are old ideas and I need to look up how valid they are nowadays and how I did it, but if you can use them, let me know. Also, there is this blog form a friend of mine with two sonataAdmin posts on there: http://php-jotter.blogspot.co.uk/2013/01/override-display-of-sonatacollectiontyp.html and http://php-jotter.blogspot.co.uk/2013/01/display-subset-or-sorted-list-of.html. Maybe that is of any use?

@rande

This comment has been minimized.

Show comment
Hide comment
@rande

rande Aug 12, 2013

Member

@caponica the http://sonata-project.org/bundles/admin/master/doc/index.html reflects lastest changes. I guess, the documentation need some main sections: References and Cookbooks.

Member

rande commented Aug 12, 2013

@caponica the http://sonata-project.org/bundles/admin/master/doc/index.html reflects lastest changes. I guess, the documentation need some main sections: References and Cookbooks.

@eminero

This comment has been minimized.

Show comment
Hide comment
@eminero

eminero Aug 14, 2013

could add something about if this is possible,
#1327

I've been looking how to implement:

  1. sonata_type_collection within sonata_type_admin
  2. sonata_type_collection within sonata_type_collection

It would be helpful. Thanks!

eminero commented Aug 14, 2013

could add something about if this is possible,
#1327

I've been looking how to implement:

  1. sonata_type_collection within sonata_type_admin
  2. sonata_type_collection within sonata_type_collection

It would be helpful. Thanks!

@rande

This comment has been minimized.

Show comment
Hide comment
@rande

rande Aug 18, 2013

Member

@caponica Can you point me PR ready to merge ?

Member

rande commented Aug 18, 2013

@caponica Can you point me PR ready to merge ?

@caponica

This comment has been minimized.

Show comment
Hide comment
@caponica

caponica Aug 18, 2013

Contributor

I think #1565, #1570, #1575 and #1577 are all ready to merge.

Contributor

caponica commented Aug 18, 2013

I think #1565, #1570, #1575 and #1577 are all ready to merge.

@rande

This comment has been minimized.

Show comment
Hide comment
@rande

rande Aug 18, 2013

Member

merged, thanks

Member

rande commented Aug 18, 2013

merged, thanks

@tiagojsag

This comment has been minimized.

Show comment
Hide comment
@tiagojsag

tiagojsag Aug 19, 2013

Contributor

@caponica aren't we missing an issue for the templates doc? Right now, there's at least one thing missing: configuring templates on a per admin service basis. Can you add the issue and tag me on it as being on it, please?

Contributor

tiagojsag commented Aug 19, 2013

@caponica aren't we missing an issue for the templates doc? Right now, there's at least one thing missing: configuring templates on a per admin service basis. Can you add the issue and tag me on it as being on it, please?

@caponica

This comment has been minimized.

Show comment
Hide comment
@caponica

caponica Aug 19, 2013

Contributor

Templating is #1531, but I think @rande missed it when tagging the issues as 'docs'

Contributor

caponica commented Aug 19, 2013

Templating is #1531, but I think @rande missed it when tagging the issues as 'docs'

@rande

This comment has been minimized.

Show comment
Hide comment
@rande

rande Aug 19, 2013

Member

tagged!

Member

rande commented Aug 19, 2013

tagged!

@rande

This comment has been minimized.

Show comment
Hide comment
@rande

rande Aug 20, 2013

Member

For information, I just add support for .. configuration-block:: 55b1cf9

I need to improve the layout, but it is a good starting point http://sonata-project.org/bundles/admin/master/doc/reference/getting_started.html#step-3-create-an-admin-service

Member

rande commented Aug 20, 2013

For information, I just add support for .. configuration-block:: 55b1cf9

I need to improve the layout, but it is a good starting point http://sonata-project.org/bundles/admin/master/doc/reference/getting_started.html#step-3-create-an-admin-service

@caponica

This comment has been minimized.

Show comment
Hide comment
@caponica

caponica Aug 20, 2013

Contributor

Excellent - I'll get onto translating the current examples into XML/YML and reformatting ones that already exist in both flavours.

Contributor

caponica commented Aug 20, 2013

Excellent - I'll get onto translating the current examples into XML/YML and reformatting ones that already exist in both flavours.

@Bladrak

This comment has been minimized.

Show comment
Hide comment
@Bladrak

Bladrak Feb 27, 2014

Member

I've updated a bit the action_list part of the documentation, feel free to reuse the table (that was quite painful to write - if anyone knows a good rst editor that handles tables, please do share ;)).

I won't have enough time to fill in all the gaps though, if anyone's interested in taking over, that would be great. Most gaps are identified thanks to @caponica; all there's left to do is to fill them.

Member

Bladrak commented Feb 27, 2014

I've updated a bit the action_list part of the documentation, feel free to reuse the table (that was quite painful to write - if anyone knows a good rst editor that handles tables, please do share ;)).

I won't have enough time to fill in all the gaps though, if anyone's interested in taking over, that would be great. Most gaps are identified thanks to @caponica; all there's left to do is to fill them.

@bensan

This comment has been minimized.

Show comment
Hide comment
@bensan

bensan Apr 1, 2014

Hey @caponica,
Would like to help in this doc effort. In the create and edit actions doc page, you have a to-do item for

a note about Routes and how disabling them disables the related action

Isn't that just redundant info for what is in this page? http://sonata-project.org/bundles/admin/master/doc/reference/routing.html. Or are you looking for something else?

bensan commented Apr 1, 2014

Hey @caponica,
Would like to help in this doc effort. In the create and edit actions doc page, you have a to-do item for

a note about Routes and how disabling them disables the related action

Isn't that just redundant info for what is in this page? http://sonata-project.org/bundles/admin/master/doc/reference/routing.html. Or are you looking for something else?

@gam6itko

This comment has been minimized.

Show comment
Hide comment
@gam6itko

gam6itko Aug 20, 2014

#2321
Documentation. Dashboard page needs some lines of explanation about AdminMenu and security context

#2321
Documentation. Dashboard page needs some lines of explanation about AdminMenu and security context

@syeo66

This comment has been minimized.

Show comment
Hide comment
@syeo66

syeo66 Dec 3, 2014

Hi everyone
Is there still something going on with the docs? The current state is quite frustrating. Todos everywhere but everything I am looking for seems to be missing.
Should I try to fix what I can?

syeo66 commented Dec 3, 2014

Hi everyone
Is there still something going on with the docs? The current state is quite frustrating. Todos everywhere but everything I am looking for seems to be missing.
Should I try to fix what I can?

@rande

This comment has been minimized.

Show comment
Hide comment
@rande

rande Dec 3, 2014

Member

@syeo66 Yes feel free to contribute.

Member

rande commented Dec 3, 2014

@syeo66 Yes feel free to contribute.

@krewetka

This comment has been minimized.

Show comment
Hide comment
@krewetka

krewetka Dec 21, 2014

Contributor

I'll try to help a bit as well as soon as I finish my project.

Export doc definitely need a lot of update, there is almost nothing there :-/

I learned quite a lot about export recently as I had to write my own one ( #1550 (comment)) so I try to join to improve docs.

Contributor

krewetka commented Dec 21, 2014

I'll try to help a bit as well as soon as I finish my project.

Export doc definitely need a lot of update, there is almost nothing there :-/

I learned quite a lot about export recently as I had to write my own one ( #1550 (comment)) so I try to join to improve docs.

@webdevilopers

This comment has been minimized.

Show comment
Hide comment
@webdevilopers

webdevilopers Mar 11, 2015

Contributor

My commit for (default) filter usage has been merged. Please feel free to have a look.

Looking forward for the export docs @krewetka ! 👍

Contributor

webdevilopers commented Mar 11, 2015

My commit for (default) filter usage has been merged. Please feel free to have a look.

Looking forward for the export docs @krewetka ! 👍

@tbyte80

This comment has been minimized.

Show comment
Hide comment
@tbyte80

tbyte80 Jul 21, 2015

I spent quite a bit of time understanding how the wiring between entities works. If you have the type "entity" (like mentioned on the "Getting Started" page) you have to specify a target class but if you want to use a type like "sonata_type_model" or "sonata_type_model_list" the target class is determined automatically. I had a bit of trouble finding out how the magic works.

Of course it's not really magic because (using doctrine ORM) the table metadata is used to determine the wired entity but this is not documented very well. The metadata of my tables were reverse engineered by doctrine using existing MyISAM tables so no relation information could be derived automatically. When I added the missing information (e.g. many-to-one relations) to the metadata and the respective entities, everything worked like a charm.

Another note on that topic "https://sonata-project.org/bundles/doctrine-orm-admin/2-2/doc/reference/form_field_definition.html" maybe under "6.1 Example" would be nice. (e.g. "Note: When using types like "sonata_type_model" the target entity is determined automatically. In order to do that the respective relations must be defined properly in your entity annotations or xml/yml Doctrine config files.")

tbyte80 commented Jul 21, 2015

I spent quite a bit of time understanding how the wiring between entities works. If you have the type "entity" (like mentioned on the "Getting Started" page) you have to specify a target class but if you want to use a type like "sonata_type_model" or "sonata_type_model_list" the target class is determined automatically. I had a bit of trouble finding out how the magic works.

Of course it's not really magic because (using doctrine ORM) the table metadata is used to determine the wired entity but this is not documented very well. The metadata of my tables were reverse engineered by doctrine using existing MyISAM tables so no relation information could be derived automatically. When I added the missing information (e.g. many-to-one relations) to the metadata and the respective entities, everything worked like a charm.

Another note on that topic "https://sonata-project.org/bundles/doctrine-orm-admin/2-2/doc/reference/form_field_definition.html" maybe under "6.1 Example" would be nice. (e.g. "Note: When using types like "sonata_type_model" the target entity is determined automatically. In order to do that the respective relations must be defined properly in your entity annotations or xml/yml Doctrine config files.")

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment