Overhaul documentation #535
Conversation
malarzm
force-pushed
the
overhaul-docs
branch
from
c20e856 to
5e2b4f7
Compare
|
|
||
| For more information, see Doctrine's `Mapping Types documentation`_. | ||
|
|
||
| .. index:: |
There was a problem hiding this comment.
No clue what this does, removed :)
There was a problem hiding this comment.
Pinging @javiereguiluz - maybe they know?
There was a problem hiding this comment.
This information is used to generate the "analytical index". Here you can see it: https://symfony.com/doc/current/genindex.html We don't publicize it because we're thinking of removing it and future doc parsers may not support it. It's very useful to create indexes for paper books, where you can display the page where some concept is explained.
There was a problem hiding this comment.
Thanks for the quick explanation! Would you recommend keeping it or is it ok if we drop this?
|
@alcaeus @jmikola on second thought I think that a complete overhaul will not be good for you to review. For example right now I'm tweaking code examples and that'll be impossible to spot basing on the diff only. What do you think about first merging the split and |
|
Sounds good to me 👍 |
There was a problem hiding this comment.
Great work splitting this up - it should be easier for newcomers to get started with ODM this way without reading through tens of pages of docs.
I've highlighted some issues we should address. I'll let you decide which issues you want to fix in this PR and which ones you want to extract to separate issues 👍
|
@javiereguiluz do you know when docs for bundles are built? Or is there maybe a way for you to trigger the build on demand? I'd like to merge this PR but also I'm a bit afraid I'll break something. Perfect for me would be to see the built docs after the built and fixing (and maybe asking you for a rebuild) shortly after not to leave docs broken for a longer time. |
|
@malarzm it's an automatic process, so I can't force a doc build for a bundle. The build is done several times per day (I don't know the exact details) so the new docs should be published soon after the merge. |
|
|
||
| .. note:: | ||
|
|
||
| Of course, you can also issue complex queries, which you'll learn more |
There was a problem hiding this comment.
In Symfony Docs we have removed words like "Of course", "simply", "obviously", etc. because they are hostile to newcomers. Maybe you want to do the same here and remove "of course".
There was a problem hiding this comment.
I'll create separate issue to go through all docs, don't want to do too many changes here as they're hard to spot. Edit: created #539
| return $this->redirectToRoute('homepage'); | ||
| } | ||
|
|
||
| Updating an object involves just three steps: |
There was a problem hiding this comment.
Most of the times, "just" is another of those bad words for newcomers. If you remove it from this phrase, no meaning is lost and it's more friendly.
|
|
||
| .. code-block:: bash | ||
|
|
||
| composer config extra.symfony.allow-contrib true |
There was a problem hiding this comment.
Not sure if this is needed anymore because Flex now asks you if you want to install a contrib package (always, just this time, only for this vendor, etc.)
|
@javiereguiluz thanks for the reply and review! I'll merge this now and hopefully it builds while I'm creating issues to take care of :) |
Currently the bundle's documentation is long and hard to navigate. This PR aims to split it and bring it up to date with Symfony 3.4+ and its standards
DocumentType(fixes Documentation: Document the additional form field types #312)I'll gladly accept help with these :)