Move bulk of render pipeline documentation to d.o handbooks

Um... that diagram... is ... large.

Perhaps it would be better as a drupal.org page attachment rather than trying to get it into api.drupal.org? Our philosophy on api.drupal.org topics and other documentation has been "Give the essentials, like to drupal.org for more details". This seems like a "more details" thing to me.

Regarding the section added to
https://api.drupal.org/api/drupal/core!modules!system!theme.api.php/grou...
needs some work. Please take a look at it. The @code sections should not be @code (that is for *blocks* of code, not individual functions/classes) and there is at least one broken @ref.

Plus it is really long and rambling, and I'm not even sure it belongs on the Render API topic page? It should either be a separate topic or just be on drupal.org IMO.

We have a whole section on drupal.org at
https://www.drupal.org/developing/api/8
documenting the Drupal 8 APIs. It should go in there.

Regarding seeing how things look while doing updates, the only way is to build your own API site, or to ask me to review patches because I have a "pretty good feel" for it.

Regarding @code we simply do not indicate in-text code on api.d.o. Things like classes and functions turn into links automatically, and we use @code *sections* when providing examples. That's how all other doc blocks in Drupal core are written.

Regarding separate topic... The rest of the Render API topic that was there before this patch is about how to use render arrays and stuff like that.

This new section is about how Drupal does stuff, not about how to use the API, which is why I don't think it belongs on this topic.

So yes, please do make it a separate topic called "Render Pipleline" and since each topic has a one-line description, that could be "Description of how Drupal renders pages".

Makes sense to me. Could link from https://api.drupal.org/api/drupal/core%21includes%21menu.inc/group/menu/8 would probably be the most likely place.

Agreed with #6. Also I would like to point out that the api.d.o landing page for Drupal 8 ( https://api.drupal.org/api/drupal/8 ) does have a link (in the Further Information section at the bottom) to https://www.drupal.org/developing/api as a whole, or rather to the D8 section, and that most of the D8 topics that you can get to from the D8 landing page also contain links to the expanded documentation on drupal.org. So yes, definitely, add a link to this new docs page, once it's created.

Also, a bit of history: We had an issue about a year ago where I was trying to get the drupal.org/developing/api docs into the Drupal Core code base for Drupal 8, or at least into a git repo where they could be edited via patches and displayed on api.drupal.org.

I got a prototype working and people tried it out... several iterations... But the end result was that the community decided they preferred to use the current system on drupal.org. I disagreed with this decision but I am not a dictator so we're stuck with the current drupal.org placement of these docs.

If you're interested, you can read through the issue to see how the discussion went -- the motivation was essentially what you said in #5. Anyway, here's the issue (although none of the demo sites is still active of course): #2106873: [meta][policy, no patch] Make Drupal 8 developer docs more discoverable

Thanks! This is definitely a step in the right direction, and the d.o page is good.

A few thoughts on the current patch:

a)

+ * @section render_pipeline The Render Pipeline
+ *
+ * For further information on the render pipeline, see
+ * https://www.drupal.org/developing/api/8/render.
  *
  * First, you need to know the general routing concepts: please read
  * @ref sec_controller first.

No blank line after @section. Also, we normally start sections with a brief introduction (especially if they're long sections), ending with a "For further information" bit, rather than just starting a section saying "For further information". It's a bit jarring. Probably instead of "First, you need to know..." we should also say something like "For background on general routing concepts, see @ref ...".

b) Don't say "please" in documentation. Ever. ;)

c) The numbered list... the API module doesn't support numbered lists and we don't have them in our API docs in general. Not introduced by this patch, but it should be replaced by a bullet list, and also before any list should be a line ending in : explaining what is in the list.

So I'd propose changing:

 * 1. Drupal uses the Symfony render pipeline. See
 *    http://symfony.com/doc/2.7/components/http_kernel/introduction.html
...

to

 * Here are some notes on the Drupal render pipeline:
 * -  Drupal uses the Symfony render pipeline. See
 *    http://symfony.com/doc/2.7/components/http_kernel/introduction.html
...

or something like this. This list is more bullet-like than numbered-like anyway, as far as I can tell.

d) There are some line wrapping issues in the numbered list. All lines should go out to nearly 80 characters within a single paragraph or bullet item.

e)

+ * 2. Within the Symfony render pipeline, there is a Drupal render pipeline
+ *    which handles controllers that return render arrays.

What does "handles controllers" mean? Also "which" requires a comma before it.

f)

+ *    into multiple formats: HTML, AJAX, Dialog and Modal. Modules can add

Serial comma needed between "Dialog, and ". And really, "Dialog" and "Modal" shouldn't be capitalized, and "Ajax" should not be all-caps.

g)

 *    to allow for decorating pages in multiple ways: no decoration at all,
 *    blocks — and e.g. Panels in contrib.

Um. First off, please stick to ASCII in API docs, no -- character. And we try to avoid "e.g."; better to write out "for example" -- you'd be surprised how often e.g. and i.e. are confused and misused. And this is not punctuated correctly... but the real problem is that I'm not sure what this means. What is decoration? How are panels decoration?

h)

+ * Routes whose controllers return the "main content" as a render array
+ * automatically have the ability to be requested in multiple ways: the main
+ * content render array can be rendered in a certain format (HTML, JSON … — 2.
+ * above) and/or in a certain decorated manner (e.g. with blocks around the main
+ * content — 3. above).

Is there a way we could combine this with the bullet list?

So a proposed rewrite of this whole section would be something like this (replacing the proposal in my review item (c) above):

The term "render pipeline" refers to the process Drupal uses to take information provided by modules and render it into a page. For more details on this process, see [link to d.o page]; for background on routing concepts, see [@ref]

There are three possible render pipelines that Drupal can use, depending on the return value of the page controller:
- If the return value is a \Symfony\Component\HttpFoundation\Response object, this is passed to the Symfony render pipeline. See http://symfony.com/doc/2.7/components/http_kernel/introduction.html
- If the return value is a render array, then a Drupal rendering pipeline specific to the type of output (HTML, Ajax, modal dialog, etc.) is used. The types of output are provided by [???? is there a class/interface people can look at to discover types of output? And maybe it would be good to explain here, briefly, how the render pipeline decides what type of output it is producing as well?]
- If the Drupal HTML pipeline is used, then an additional "decoration" process is included. For example, the core Blocks module adds blocks in regions to the main page content; the contributed Panels module is another example. [Again maybe say what class/interface these "decoration" modes are, and how Drupal decides which one is being used?]

[and then all the @see lines?]

Looking good! A few minor things still to address:

a) Unfortunately paragraph breaks don't work in bullet lists in API docs. Sorry.

 * - Within the Symfony render pipeline, there is a Drupal render pipeline,
+ *   which handles controllers that return render arrays. (Symfony's render
+ *   pipeline only knows how to deal with Response objects, this pipeline
+ *   converts render arrays into Response objects.)
+ *   These render arrays are considered the main content, and can be rendered
+ *   into multiple formats: HTML, Ajax, dialog, and modal. Modules can add
+ *   support for more formats, by implementing a main content renderer.

I think the thing to do here is to make them two separate bullets, which I think is OK.

b)

 *   pipeline only knows how to deal with Response objects, this pipeline
+ *   converts render arrays into Response objects.)

This is a comma splice. Replace , with ;

c)

+ *   into multiple formats: HTML, Ajax, dialog, and modal. Modules can add
+ *   support for more formats, by implementing a main content renderer.

Can we mention how to do this briefly? Such as something like ", which is a plugin annotated with \Drupal\Foo\Bar\Whatever annotation". (that will turn into a link to the plugin annotation class, which will have more information). Possibly it's one of your @see lines, but including the reference right here will make it more obvious to developers.

c)

+ * Routes whose controllers return a \Symfony\Component\HttpFoundation\Response
+ * object are fully handled by the Symfony render pipeline (1. above).
+ *
+ * Routes whose controllers return the "main content" as a render array
+ * automatically have the ability to be requested in multiple ways: the main
+ * content render array can be rendered in a certain format (HTML, JSON … — 2.
+ * above) and/or in a certain decorated manner (e.g. with blocks around the main
+ * content — 3. above).

We don't have numbers so this is confusing. I think we can just take out the references to 1, 2, 3 and it will be clear enough.

Maybe the second paragraph could be:

Routes whose controllers return the "main content" for the page as a render array can be requested in different formats (HTML, JSON, etc.), and/or in a "decorated" manner, as described above.

I'm still not convinced we need these two paragraphs separate from the bullet list. It still seems to me that integrating the information into the above bullet list would be clearer and would require less repetition and "see above" kinds of references. But I don't feel too strongly about it.

d)

+ * - Finally, within the HTML main content renderer, there is another pipeline,
+ *   to allow for decorating the main content in multiple ways: no decoration at
+ *   all (just showing the main content), blocks (blocks positioned in regions
+ *   around the main content) -- and for example Panels in contrib.

At the end of this, maybe change it to:
... around the main content), and the contributed Panels module, for example.

Also I think it might be useful to do something like (c) here to explain where these "decorators" come from or what class they are, or how it's decided which one to use for a given page?

That looks good! One very very very minor thing: On another Documentation issue, there's an effort underway to remove ... from documentation. So let's not introduce one here:

+ * requested in multiple formats (HTML, JSON …) and/or in a "decorated" manner,

Just use ", etc." instead. Then you can RTBC your own patch and we can all rejoice. Thanks a bunch!

Great to see this coming together :)

Making the small change as per #14 and marking it as RTBC as per that comment.

Needs a reroll.

@Wim Leers: I think you picked the interdiff from something else. Since this is just a reroll, I don't think an interdiff is even necessary (or possible).

Docs are not frozen in beta. Committed 505e393 and pushed to 8.0.x. Thanks!