first import of the "Official Best Practices" book
Fixed some technical problems as suggested by Wouter
Added an index directive to the first chapter
updated fabpot/sphinx-php module reference
added the missing "best-practice" directive import in Sphinx configuration
Renamed "official best practices" to "best practices"
Fixed some typos reported by @henrikbjorn
Updated the sphinx submodule to ad support for best-practice directive
feature #4327 First import of the "Official Best Practices" book (javiereguiluz)

This PR was merged into the 2.3 branch.

Discussion
----------

First import of the "Official Best Practices" book

As promised, this Pull Request adds the source files of the new "Official Best Practices" book recently published at symfony.com/best-practices.

Similarly to any other Symfony documentation, the community is allowed, and even encouraged, to propose improvements and fixes to this document. However, given the special nature of this document, we'd like to clarify what proposals will be accepted and what proposals will not.

**The following will be happily accepted:**

  * Typos and grammar fixes.
  * Objective errors (errors in code, technical arguments that are irrelevant or wrong, etc.)
  * Rewordings and simplifications of confusing explanations.
  * Proposals to add new best practices not covered so far.

**The following will not make it:**

  * Complete rewriting of the existing best practices (for instance, a proposal to change *"use annotations ..."* to *"don't use annotations ..."* won't be accepted)

Before some of you get mad at us, please let us explain the purpose of this book. The "Official Symfony Best Practices" explains the recommendations that the original creator of Symfony thinks you should follow to develop web applications.

When we talk about opinions instead of facts, it's really hard to tell when someone is wrong. For instance, who of the following developers you think is wrong?

  * *Developer A*: you should not use annotations. They may be convenient for this and that, but they have these other problems.
  * *Developer B*: you should use annotations. They may have these problems, but it's worth it because of this and that convenience.

For us, both opinions are valid, in the sense that they are not promoting universal truths. It's perfectly fine to think that annotations are good and/or bad.

This is the reason why this book is not about the creator of Symfony thinking that he is smarter than all of us. And this is definitely not the list of perfect practices or mandatory practices. This is just an opinionated list of recommendations by the original creator of Symfony. If you happen to follow them (all or some) that's fine. If you don't want to follow them or even if you think that they are wrong, that's perfectly fine too.

Let us make it clear again: this is not a list of universal truths or mandatory practices. This is just a list of opinions about how to do things. Follow them or not at your will.

If the Symfony community wants to create their own set of "community best practices", that's great! That way, people will have more best practices to choose from and more information to make better decisions.

We really hope things are more clear now. If not, please comment us your concerns and we'll better explain things for you.

------

Speaking from a strictly technical point of view, I'd like to warn documentation maintainers (@weaverryan, @WouterJ and @xabbuh) that I have no idea about the process to follow when adding a new book to the Symfony documentation.

The things that for sure are not going to work right now are the following:

  * On `symfony.com` we don't have the CSS style to display the best practices. We'll add it really soon to match the style of the existing PDF file.
  * On `symfony.com` the URL `http://symfony.com/doc/current/best_practices/index.html` now displays a regular web page. Once this book is added to the documentaton pipeline, we'll remove that page to show instead the index of this book.
  * The PDF generation for this book isn't prepared yet, so we'll have to wait a few days to set everything up.

Commits
-------

7eb9367 Updated the sphinx submodule to ad support for best-practice directive
d001da8 Fixed some typos reported by @henrikbjorn
d12cfe5 Renamed "official best practices" to "best practices"
af6b70b added the missing "best-practice" directive import in Sphinx configuration
30b9c45 updated fabpot/sphinx-php module reference
f100fc0 Added an index directive to the first chapter
d317925 Fixed some technical problems as suggested by Wouter
2c2000a first import of the "Official Best Practices" book