Refactor docs #111

ddeboer · 2014-07-20T20:59:04Z

Fix #94.

dbu · 2014-07-21T06:38:15Z

Resources/doc/overview.rst

+.. code-block:: bash
+
+    $ composer require sensio/framework-extra-bundle
+


we should also give the line to instantiate the bundle in the kernel, no?

dbu · 2014-07-21T06:53:17Z

great work, this is coming good! added some comments so we see the open ends in the PR and some inputs.

dbu · 2014-07-21T10:59:43Z

Resources/doc/reference/configuration/rules.rst

+Rules
+=====
+
+Configure the bundle under the ``fos_http_cache`` key. The configuration


the first sentence is a general intro and does not belong here.

dbu · 2014-07-28T06:48:21Z

@ddeboer how is the state here? i think this is the last blocker for RC1 and i would love to release that this week. anything i can help with here?

ddeboer · 2014-07-28T09:20:54Z

I guess working on the same doc files together at the same time will only complicate things. I’ll push an update tonight, so if it would be most helpful if you could go through that and your criticism.

By the way, do you want to skip beta and go directly to RC?

dbu · 2014-07-28T09:55:07Z

ups, i thought we have a beta already. hm. lets tag a beta then and announce it, as soon as this PR is merged.

and agreed that editing in the same place is probably tricky. ping me when you pushed your update. and then lets try to wrap it up and maybe add some follow-up tickets for things that could be improved, so we can work separately on them.

ddeboer · 2014-07-28T09:55:37Z

Sounds like a plan!

ddeboer · 2014-07-28T20:45:26Z

Pushing some updates. A built version is available at http://foshttpcachebundle.readthedocs.org/en/refactor-docs/.

ddeboer · 2014-07-28T21:23:51Z

@dbu Not sure where this should go (removed it from the docs for now). Can you place it where it belongs?

    **TODO: MOVE** When using ESI, you will want to purge individual fragments. To generate the
    corresponding ``_internal`` route, inject the ``http_kernel`` into your controller and
    use HttpKernel::generateInternalUri with the parameters as in the twig
    ``render`` tag.

Also, can you do the Flash Message config chapter?

ddeboer · 2014-07-28T21:32:24Z

Still to do:

Flash Message config (@dbu) => various tweaks and cleanups #116
Properly include match partial in all relevant config chapters
Clean up Rules chapters (cache, invalidation, tags).

dbu · 2014-07-29T07:22:20Z

great. sure i can handle the flash message thingy. i will also look into some sort of common header for each feature chapter to say whether it needs the cache manager and varnish configuration or something like that. with the split between library and bundle, this is a bit tricky to see.

dbu · 2014-07-29T20:58:37Z

Resources/doc/reference/annotations.rst

-You can also use expressions_ in the route parameter values:
-
-.. code-block:: php
+You can also use expressions_ in the route parameter values::


where is the expression in the next example? it looks very similar to the previous one to me.

It does indeed. The difference is that latest does not come from the request attributes (it’s hard-coded) and id does. They look the same because the InvalidationSubscriber tries to evaluate each parameter as an expression against request attributes, and fails silently when it doesn’t seem to be an expression (as in the case of latest).

Do you have an idea as to how we could make this clearer? Should we make the behaviour more explicit?

ah, so "id" is tried to be the expression looking for the value id and if that fails, it is the string "id"?

maybe add a note with what you just explained here. its valuable information, also when wanting a static expression that happens to match a parameter name...

Exactly. You could force a string, e.g. id, by giving "'id'" (extra quotes). This is different from how we do tags: @Tag("string") versus @Tag(expression="id"). I think I prefer this inconsistency over something like: @InvalidateRoute("route", params={"type" = {"expression": "id"}}) (is this even possible?). Do you agree? I’ll update the docs to make this clearer.

theoretically you could do params_expression (or param_expressions?). and then even merge the two. if that is no big pain, we might actually want to do that to avoid that WTF moment when a name hits a parameter name. doing it later would be a BC problem...

What would the syntax be like, in your proposal? I think just supplying one list of route params, and differentiating between them with a literal string versus key/value {"expression": "id"} is most user-friendly. Do you have time to open a PR for this?

created #117, lets see. i think we should merge now, and then clean that bit up.

if you agree, can you squash and merge?

dbu · 2014-07-29T22:16:34Z

ftr: i decided to drop this ESI hint. its extremly specific and if anything would belong somewhere into the symfony cookbook, not here.

ddeboer · 2014-07-30T09:53:01Z

Resources/doc/features/helpers.rst

+
+.. toctree::
+
+    helpers/flash-message


Do we actually need a separate Helpers chapter? Should more items be listed here, or do we expect any to pop up soon? What about just upgrading the Flash Message helper to a fully-fledged Feature chapter?

what i like about this is that it makes this thing less prominent than the rest. it is less important. and we might turn up with other things too. but if you prefer, you can also move this, and we can restructure when/if we have more helpers turning up.

I have no strong feelings about this. The helper just looks a bit lonely in there. 😉

ddeboer · 2014-07-30T09:55:24Z

Okay, pushed my last changes. One question remaining about the Flash Message chapter @dbu. We’ll revisit the tags config examples when #117 is merged. Otherwise, this is ready to be squashed and rebased.

@tag

Fix #94. Add bundle activation to installation Improve @tag section in Annotations Include match partial in invalidation chapter Update user context docs Fix typos Add chapter intros Add chapter headers Add Debug config chapter Add flash message chapter (todo) Update proxy client chapter Remove default config chapter Add Configuration chapter header Re-organise configuration chapters Match is now linked to instead of included, and included in the TOC too.

* fix links to FOSHttpCache docs * a little clean-up

ddeboer · 2014-07-30T10:02:22Z

Okay, squashed. If Travis is green you may press the big green button. 😄

Refactor docs

dbu · 2014-07-30T10:42:44Z

yay, great work!

dbu reviewed Jul 21, 2014
View reviewed changes

dbu reviewed Jul 29, 2014
View reviewed changes

dbu mentioned this pull request Jul 30, 2014

InvalidateRoute annotation should be explicit about expression or not #117

Closed

ddeboer reviewed Jul 30, 2014
View reviewed changes

ddeboer and others added 3 commits July 30, 2014 12:01

various tweaks and cleanups

c9ee056

Finalise docs

308be68

* fix links to FOSHttpCache docs * a little clean-up

ddeboer changed the title ~~[WIP] Refactor docs~~ Refactor docs Jul 30, 2014

dbu added a commit that referenced this pull request Jul 30, 2014

Merge pull request #111 from FriendsOfSymfony/refactor-docs

51bee50

Refactor docs

dbu merged commit 51bee50 into master Jul 30, 2014

dbu deleted the refactor-docs branch July 30, 2014 10:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor docs #111

Refactor docs #111

ddeboer commented Jul 20, 2014

dbu Jul 21, 2014

ddeboer Jul 21, 2014

dbu commented Jul 21, 2014

dbu Jul 21, 2014

dbu commented Jul 28, 2014

ddeboer commented Jul 28, 2014

dbu commented Jul 28, 2014

ddeboer commented Jul 28, 2014

ddeboer commented Jul 28, 2014

ddeboer commented Jul 28, 2014

ddeboer commented Jul 28, 2014

dbu commented Jul 29, 2014

dbu Jul 29, 2014

ddeboer Jul 30, 2014

dbu Jul 30, 2014

ddeboer Jul 30, 2014

dbu Jul 30, 2014

ddeboer Jul 30, 2014

dbu Jul 30, 2014

dbu commented Jul 29, 2014

ddeboer Jul 30, 2014

dbu Jul 30, 2014

ddeboer Jul 30, 2014

ddeboer commented Jul 30, 2014

ddeboer commented Jul 30, 2014

dbu commented Jul 30, 2014

		.. code-block:: bash

		$ composer require sensio/framework-extra-bundle

Refactor docs #111

Refactor docs #111

Conversation

ddeboer commented Jul 20, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dbu commented Jul 21, 2014

Choose a reason for hiding this comment

dbu commented Jul 28, 2014

ddeboer commented Jul 28, 2014

dbu commented Jul 28, 2014

ddeboer commented Jul 28, 2014

ddeboer commented Jul 28, 2014

ddeboer commented Jul 28, 2014

ddeboer commented Jul 28, 2014

dbu commented Jul 29, 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dbu commented Jul 29, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ddeboer commented Jul 30, 2014

ddeboer commented Jul 30, 2014

dbu commented Jul 30, 2014