[WIP] Revamp the documentation #2649

wouterj · 2014-12-24T18:20:04Z

I don't have to explain the idea behind this PR, I think. SonataAdminBundle is known to be very hard to work with, mostly due to it's "not that great" documentation. There is lots of duplication and it's more written in a "complete reference style" than a nice-to-read book.

That's why I've choosen SonataAdminBundle as my christmas project this year and with this PR, I want to give you the christmas present: A complete new, easy to read, guide for beginners.
In the end, this will replace most of the hard to understand things in the reference guide. I'm also planning to remove the great amount of duplication between the adapter bundles.

To be honest, I failed. I wanted to have it finished before Christmas, but I didn't have enough time. That's why I present you the first 3 chapters here, while working on the other chapters (I think it's going to be around 5 chapters).

I'm welcoming all feedback on this PR.

I wish the complete Sonata team, it's contributors and all other people reviewing this PR a merry christmas and very happy new year! 🎄 🎅 ⛄ 🎆

dantleech · 2014-12-24T18:25:23Z

Resources/doc/getting_started/creating_an_admin.rst

+        // ...
+
+        /**
+        * @ORM\ManyToOne(targetEntity="Category", inversedBy="blogPosts")


Indentation

cryptiklemur · 2014-12-24T18:31:03Z

Thank you @wouterj !

dantleech · 2014-12-24T18:31:14Z

Resources/doc/getting_started/the_form_view.rst

+database. This means the form view just needs 3 fields: title, body and
+category.
+
+The title and body fields are simple text and textarea fields, you can add them


simple "text" and "textarea" (quotes)

wouterj · 2014-12-24T22:57:21Z

Thank you, @dantleech and @greg0ire. I've applied most of your suggestions.

greg0ire · 2014-12-24T23:05:58Z

Resources/doc/getting_started/the_form_view.rst

+---------------------------
+
+If you already know the `Symfony Form component`_, the ``FormMapper`` will look
+very similair.


greg0ire · 2014-12-24T23:15:40Z

Merry Christmas to you too and thanks a lot for the present!

pulzarraider · 2014-12-25T05:39:26Z

Resources/doc/getting_started/creating_an_admin.rst

+
+Now you've created the admin class for your category, you probably want to know
+how this looks like in the admin interface. Well, let's find out by going to
+http://localhost:8000/admin


Here can be information, that this tutorial expects a server running on port 8000 (Apache/Nginix/Built-in php).

I've put that in the first chapter of the guide:

This tutorial assumes you are using the build-in server using the
php app/console server:start (or server:run) command.

pulzarraider · 2014-12-25T05:40:45Z

Thank you @wouterj. Merry Christmas to you all!

rande · 2014-12-25T20:52:00Z

Resources/doc/getting_started/installation.rst

+    available in this bundle. The bundle also uses `Bower <http://bower.io/>`_,
+    so you can use bower to handle your assets. To make sure you get the
+    dependencies that match the version of SonataAdminBundle you are using, you
+    can make bower use the local bower dependency file, like this:


Using bower is not required as all assets are bundled inside the bundle

Really? Then why I get 404 errors and Uncaught ReferenceError: jQuery is not defined ? Even when I am using Bower?

@smilesrg Jquery and some other js/css dependencies were moved to SonataCoreBundle. You are probably using dev-master of SonataAdmin, but tagged branch of SonataCoreBundle.

OskarStark · 2015-10-09T08:31:28Z

Resources/doc/getting_started/the_form_view.rst

+
+    $formMapper
+        ->tab('Post')
+            ->group('Content', ...)


i would say group() is wrong, with() should be correct

wouterj · 2015-10-10T10:20:39Z

@OskarStark rebased & applied your comments.

OskarStark · 2015-10-10T15:26:27Z

please fix travis @wouterj

Warning, treated as error:
/home/travis/build/sonata-project/SonataAdminBundle/Resources/doc/getting_started/installation.rst:29: ERROR: Unknown target name: "sonatadoctrinemongodbadminbundle".

Thank you 👍

wouterj · 2015-10-10T15:51:05Z

done

greg0ire · 2015-10-10T17:11:56Z

Warning, treated as error:

/home/travis/build/sonata-project/SonataAdminBundle/Resources/doc/index.rst:17: ERROR: Error in "toctree" directive:

invalid option block.

.. toctree::
    :maxdepth: 1
    :numbered

    getting_started/installation
    getting_started/creating_an_admin
    getting_started/the_form_view
    getting_started/the_list_view

What option is it complaining about ?

wouterj · 2015-10-10T17:17:02Z

@greg0ire it was complaining about the syntax (missing colon after :numbered).

greg0ire · 2015-10-10T17:23:49Z

Thanks for fixing that!

OskarStark · 2015-10-12T07:46:01Z

@wouterj , please squash your commits into one, after that i can finally push the button 😄

soullivaneuh · 2015-10-12T07:54:06Z

@OskarStark please check if this will be mergeable to master.

OskarStark · 2015-10-12T08:05:50Z

i checked, it is 👍

Revamp the documentation and added "Getting started" as own chapter

OskarStark · 2015-10-19T15:23:06Z

Thank you for this awesome work @wouterj

OskarStark · 2015-10-19T15:23:39Z

@soullivaneuh would be great if you could merge 2.3 in current master

Thank you

rande · 2015-10-19T21:53:02Z

Awesome! Thanks for this contribution ;)

rande · 2015-10-21T08:31:24Z

I think some images need to be resized :)

https://sonata-project.org/bundles/admin/2-3/doc/getting_started/creating_an_admin.html

soullivaneuh · 2015-10-21T08:36:34Z

I think some images need to be resized :)

Could not be managed by the website itself? Image resize, click to enlarge...

dantleech reviewed Dec 24, 2014
View reviewed changes

greg0ire reviewed Dec 24, 2014
View reviewed changes

pulzarraider reviewed Dec 25, 2014
View reviewed changes

rande reviewed Dec 25, 2014
View reviewed changes

OskarStark reviewed Oct 9, 2015
View reviewed changes

wouterj added 6 commits October 10, 2015 12:18

Wrote first chapters

dd63c30

First batch of fixes

e21933a

Applied some comments

d8a9871

Finished the list view article

33ac59c

Added articles to the index

ff58baf

Finish getting started articles

159056d

wouterj force-pushed the revamp_docs branch from 2b77691 to 2566dc1 Compare October 10, 2015 10:20

Fixes

b94a4bc

wouterj force-pushed the revamp_docs branch from 2566dc1 to b94a4bc Compare October 10, 2015 15:51

Fix syntax

0355b61

OskarStark added a commit that referenced this pull request Oct 19, 2015

Merge pull request #2649 from WouterJ/revamp_docs

2c11eb5

Revamp the documentation and added "Getting started" as own chapter

OskarStark merged commit 2c11eb5 into sonata-project:2.3 Oct 19, 2015

wouterj deleted the revamp_docs branch October 19, 2015 22:43

OskarStark mentioned this pull request Oct 23, 2015

use composer command instead of editing json file symfony/symfony-docs#5829

Merged

jvasseur mentioned this pull request Nov 10, 2015

Unable to generate a URL for the named route "admin_sonata_user_user_create" #3412

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Revamp the documentation #2649

[WIP] Revamp the documentation #2649

wouterj commented Dec 24, 2014

dantleech Dec 24, 2014

cryptiklemur commented Dec 24, 2014

dantleech Dec 24, 2014

wouterj commented Dec 24, 2014

greg0ire Dec 24, 2014

greg0ire commented Dec 24, 2014

pulzarraider Dec 25, 2014

wouterj Dec 28, 2014

pulzarraider commented Dec 25, 2014

rande Dec 25, 2014

smilesrg Dec 27, 2014

pulzarraider Dec 28, 2014

OskarStark Oct 9, 2015

wouterj commented Oct 10, 2015

OskarStark commented Oct 10, 2015

wouterj commented Oct 10, 2015

greg0ire commented Oct 10, 2015

wouterj commented Oct 10, 2015

greg0ire commented Oct 10, 2015

OskarStark commented Oct 12, 2015

soullivaneuh commented Oct 12, 2015

OskarStark commented Oct 12, 2015

OskarStark commented Oct 19, 2015

OskarStark commented Oct 19, 2015

rande commented Oct 19, 2015

rande commented Oct 21, 2015

soullivaneuh commented Oct 21, 2015

[WIP] Revamp the documentation #2649

[WIP] Revamp the documentation #2649

Conversation

wouterj commented Dec 24, 2014

Choose a reason for hiding this comment

cryptiklemur commented Dec 24, 2014

Choose a reason for hiding this comment

wouterj commented Dec 24, 2014

Choose a reason for hiding this comment

greg0ire commented Dec 24, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pulzarraider commented Dec 25, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wouterj commented Oct 10, 2015

OskarStark commented Oct 10, 2015

wouterj commented Oct 10, 2015

greg0ire commented Oct 10, 2015

wouterj commented Oct 10, 2015

greg0ire commented Oct 10, 2015

OskarStark commented Oct 12, 2015

soullivaneuh commented Oct 12, 2015

OskarStark commented Oct 12, 2015

OskarStark commented Oct 19, 2015

OskarStark commented Oct 19, 2015

rande commented Oct 19, 2015

rande commented Oct 21, 2015

soullivaneuh commented Oct 21, 2015