Improve the docs #1743
Improve the docs #1743
Conversation
|
@xabbuh do you have some time to review this please? :) |
Resources/doc/2-the-view-layer.rst
Outdated
| sophisticated `serializer`_ created by Johannes Schmitt and integrated via the | ||
| `JMSSerializerBundle`_. | ||
| To do so, you first need to create a ``View`` instance in your controller | ||
| action. The ``View`` object is a simple data holder that describes the response |
Resources/doc/2-the-view-layer.rst
Outdated
| } | ||
|
|
||
| or it is possible to use lazy-loading: | ||
| .. note:: |
Resources/doc/index.rst
Outdated
| Installation is a quick (I promise!) one-step process: | ||
| Before using this bundle in your project, add it to your composer.json file: | ||
|
|
||
| .. code-block:: bash |
Resources/doc/index.rst
Outdated
| three possibilities **in this order** to decide which serializer to use: | ||
|
|
||
| #. The service ``fos_rest.service.serializer`` if it is configured (must be an | ||
| instance of ``FOS\RestBundle\Serializer``). |
There was a problem hiding this comment.
this line must be indented by three spaces
Resources/doc/index.rst
Outdated
|
|
||
| 1. :doc:`Setting up the bundle <1-setting_up_the_bundle>` | ||
| .. _`JMSSerializerBundle`: https://github.com/schmittjoh/JMSSerializerBundle |
There was a problem hiding this comment.
Maybe link to the bundle's documentation (http://jmsyst.com/bundles/JMSSerializerBundle) instead?
| @@ -1,55 +0,0 @@ | |||
| Step 1: Setting up the bundle | |||
There was a problem hiding this comment.
Do we really want to delete the whole file? There may be references out there linking to it.
There was a problem hiding this comment.
@javiereguiluz Is there a chance we are able to create a redirection map for bundles featured on symfony.com like we do it for the Symfony docs?
There was a problem hiding this comment.
I'm afraid it's not possible and we don't plan to implement that feature because it won't be simple to do it. However, I propose you a solution that will work:
- You maintain this article, but delete all the original contents.
- You put in this article some informational message like: "we moved this content to this other article: xxxxxx (link to the new contents)"
- You include this article in a hidden TOC to avoid RST issues saying that the article is not included in any TOC (to do that, just add
:hidden:to the.. toctree::directive). Since it's a hidden TOC, the article is not visible by anyone except those clicking on old links and going directly to this article.
We do the same in Symfony Docs to "hide" some contents. Example:
Learn more about Routing
------------------------
.. toctree::
:hidden:
controller
.. toctree::
:maxdepth: 1
:glob:
routing/*
|
@xabbuh thanks for your review. I'm sorry I won't be able to fix your comments right now (I'm really running out of time) so if you can please do the changes you want otherwise maybe I'll have more time in october. |
|
@GuilhemN of course, I'll take care of it |
|
I fixed your comments, not sure what to do about the broken links though. |
|
This needs a rebase. Do you plan to finish it? |
|
I don't really remember the changes i've done here but i'll give it a look this week and check if it's still worth merging. By the way, thanks a lot for the cleanup you've done in the repository, it's a huge work that was very much needed. |
|
This a time consuming task as the docs have been modified quite a lot since, it would probably be easier to redo it from scratch at this point so let's just close it for now :) |
I'd like to make the docs less boring to read and describing less edge cases.
So here a first step :)