Modernize documentation #618
Conversation
|
|
|
@SzymonKaminski thank you a lot for your effort and this PR! Just wanted you to know that we need to handle #613 first, then this PR will prolly need a rebase |
|
@SzymonKaminski sorry for the long time, but we've finally merged #613 and merged it up into |
Use https everywhere, replace broken anchor links with working alternatives. Reword paragraph mentioning DoctrineExtensions adding links to actual package and bundle documentation.
Avoid words like 'just', 'simply' and making any assumptions about knowledge of a user. Replace 'easiest' with 'recommended'.
Avoid repetitions of words, use punctuation marks in proper places.
Replace Acme bundles with App. Remove generate:bundle command.
Update file paths to new directory structure. Update installation guide to cover required steps when not using Flex. Prefer project_dir over root_dir.
Reorder `use` statements, prefer [] over array(). Fix typos. Remove duplicated DefaultController example as the first one includes autowired DocumentManager already. Remove dynamic findOneBy methods examples.
UserInterface anchor no longer exists in Symfony docs - linking to Security.
SzymonKaminski
force-pushed
the
update_docs
branch
from
2c78b4f
to
71e4b28
Compare
|
The lint action is green and I believe I haven't missed anything during the rebase 🎉 |
| this is pretty easy. Add the following method to the ``DefaultController`` | ||
| of the bundle: | ||
| setter methods, you're ready to persist data to MongoDB. Let's try it from inside | ||
| a controller. Create new Controller class inside source directory of your project: |
There was a problem hiding this comment.
DefaultController was already created in this chapter, please bring back the part about adding a new method to it
There was a problem hiding this comment.
At the top of the file I've removed section with bin/console generate:bundle --namespace=Acme/StoreBundle command from which DefaultController came from
There was a problem hiding this comment.
Ah sorry then 👍 so we need to just change
| a controller. Create new Controller class inside source directory of your project: | |
| a controller. Create a new Controller class inside source directory of your project: |
Also what do you think about having entire controller in example? Showing only method to add made sense when controller was already there, now it looks a bit off IMO
There was a problem hiding this comment.
Ok, will add class name to the example. Also the missing file path inside codeblock in the next section Fetching Objects from MongoDB. That example doesn't need full class, right?
There was a problem hiding this comment.
That example doesn't need full class, right?
Right 👍
|
On a weekend thought: this is PR is so good I'm gonna change that one thing off after merging, let's not keep this open anymore. Thanks a lot @SzymonKaminski! 🎉 |
This PR aims to modernize the bundle's documentation by resolving several opened issues.
All URLs found in docs were checked for correctness and updated accordingly, new links were added where they could be helpful for newcomers (Form, Security, environment variables) - Verify things we talk about and link to are still relevant #538
Code examples no longer refer to Acme bundles; usage of Symfony Flex is recommended, configuration steps for projects not using Flex were updated for completeness - Remove usage of bundles from documentation #536
code examples comply with Doctrine coding standard with few exceptions mentioned below - Modernize documentation code #544
some sentences were reworded to avoid belittling words - Be keen to newcomers #539 and https://symfony.com/doc/current/contributing/documentation/standards.html
a tip mentioning Replica Set option in connection string was added with link to relevant MongoDB docs page - Replica set connection issue #374
typos were fixed and unclear paragraphs were reworded
One twig template file still uses code-block
html+jinjaashtml+twigwould not work currently as mentioned in #613 (review)phpcs.xml.distfile from this repository was used when running phpcs in SF skeleton, therefore parameter and return type hints were not added. Additionally@MongoDBannotations spanning multiple lines (instead of one) were left unchanged.Every issue is resolved in separate commit containing brief description of changes, unless sensible splitting of given line(s) was hard to achieve.
Using doctrine/rst-parser directly in my Symfony skeleton or SenseException/rst-builder produced errors as mentioned in #613 (comment) (e.g. Unknown directive: "tip" for line ".. tip::").
I set up doctrine-website locally and confirmed that docs based on this PR can be built without any errors.