Fill in @defgroup/topic docs for Render overview

Thanks @jhodgdon! I don't have time to review this right this minute but I'm tagging this issue so it shows up on http://drupaltwig.org, this looks like really important documentation to get in place for the theme system.

Excellent work, @jhodgdon! Very helpful clarifications and grammar clean-ups. Technically, I see no issues. Otherwise:

1. +++ b/core/modules/system/core.api.php
   @@ -372,12 +372,73 @@
   + *
   + * For further information on the Theme and Render APIs, see:
   + * - https://drupal.org/documentation/theme
   + * - https://drupal.org/developing/modules/8
   + * - https://drupal.org/node/722174
   + * - https://drupal.org/node/933976
   + * - https://drupal.org/node/930760
   + *
   + * @todo Check these links. Some are for Drupal 7, and might need updates for
   + *   Drupal 8.
   

   Yes, the last three links need updates/review for Drupal 8.

2. +++ b/core/modules/system/theme.api.php
   @@ -3,73 +3,90 @@
   + * Functions and templates for the user interface that themes can override.
   + *
   + * Drupal's theme system ideally allows a theme to have complete control over
   + * the appearance of the site, which includes both the markup and the CSS used
   + * to style the markup. For this system to work, modules, instead of writing
   

   Why the word "ideally"? Maybe "Drupal's theme system allows a theme to have nearly complete control over the appearance of the site,..." ?

3. +++ b/core/modules/system/theme.api.php
   @@ -86,32 +103,51 @@
   + * @section sec_suggestions Theme hook suggestions
   + * In some cases, instead of calling the base theme hook implementation (either
   + * the default provided by the module that defined the hook, or the override
   + * provided by the theme), the theme system will instead look for "suggestions"
   + * of other hook names to look for. Suggestions can be specified in several
   + * ways:
   + * - In a render array, the '#theme' property (which gives the name of the hook
   + *   to use) can be an array of theme hook names instead of a single hook name.
   + *   In this case, the render system will look first for the highest-priority
   + *   hook name, and if no implementation is found, look for the second, and so
   + *   on. Note that the highest-priority suggestion is at the end of the array.
   + * - In a render array, the '#theme' property can be set to the name of a hook
   + *   with a '__SUGGESTION' suffix. For example, in search results theming, the
   + *   hook 'item_list__search_results' is given. In this case, the render system
   + *   will look for theme templates called item-list--search-results.html.twig,
   + *   which would only be used for rendering item lists containing search
   + *   results, and if this template is not found, it will fall back to using the
   + *   base item-list.html.twig template. This type of suggestion can also be
   + *   combined with providing an array of theme hook names as described above.
   + * - A module can implement hook_theme_suggestions_HOOK(). This allows the
   + *   module that defines the theme template to dynamically return an array
   + *   containing specific theme hook names (presumably with '__' suffixes as
   + *   defined above) to use as suggestions. For example, the Search module
   + *   does this in search_theme_suggestions_search_result() to suggest
   + *   search_result__PLUGIN as the theme hook for search result items, where
   + *   PLUGIN is the machine name of the particular search plugin type that was
   + *   used for the search (such as node_search or user_search).
   + *
   + * @section sec_alternate_suggestions Suggesting Alternate Hooks
   + * Modules can also alter the theme suggestions provided using the mechanisms
   + * of the previous section. There are two hooks for this: the
   + * theme-hook-specific hook_theme_suggestions_HOOK_alter() and the generic
   + * hook_theme_suggestions_alter(). These hooks get the current list of
   + * suggestions as input, and can change this array (adding suggestions and
   + * removing them).
   + *
   

   The title of the second section seems a little too similar to the first. Instead of "Suggesting Alternate Hooks" maybe use the heading "Altering Theme Hook Suggestions" ?

Adding Twig tag I accidentally removed with last comment.

Thanks, @jhodgdon.

Looking at those links again, I see all three pages are very tightly coupled to D7, and instead of rewriting them, I think new pages should be created for D8 and used in this patch (linked from the other pages where appropriate).

Fair enough. Those links are as good as they get for now, and this patch is full of nothing but helpful clarifications and additions to our docs. RTBC.

Sorry for the delay on this, this looks really great.

Committed and pushed to 8.x. Thanks!