_theme() is now an internal function; Move the Theming documentation to a better-suited page in the documentation [#2215587]

Problem/Motivation

#2173655: Refactor theme() to _theme(); make it a private API to discourage module developers from circumventing the renderable build system converted theme() to _theme(), an internal function. Much of the documentation associated with this function, although accurate, is associated with a function that should not be called directly. This creates a little tension.

Proposed resolution

Move the following block of documentation to an appropriate page within the Drupal 8 documentation. #2148255: [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files may have a suitable category once it is committed.

 * @section sec_theme_hooks Theme Hooks
 * Most commonly, the first argument to this function is the name of the theme
 * hook. For instance, to theme a taxonomy term, the theme hook name is
 * 'taxonomy_term'. Modules register theme hooks within a hook_theme()
 * implementation and provide a default implementation via a function named
 * theme_HOOK() (e.g., theme_taxonomy_term()) or via a template file named
 * according to the value of the 'template' key registered with the theme hook
 * (see hook_theme() for details). Default templates are implemented with the
 * Twig rendering engine and are named the same as the theme hook, with
 * underscores changed to hyphens, so for the 'taxonomy_term' theme hook, the
 * default template is 'taxonomy-term.html.twig'.
 *
 * @subsection sub_overriding_theme_hooks Overriding Theme Hooks
 * Themes may also register new theme hooks within a hook_theme()
 * implementation, but it is more common for themes to override default
 * implementations provided by modules than to register entirely new theme
 * hooks. Themes can override a default implementation by implementing a
 * function named THEME_HOOK() (for example, the 'bartik' theme overrides the
 * default implementation of the 'menu_tree' theme hook by implementing a
 * bartik_menu_tree() function), or by adding a template file within its folder
 * structure that follows the template naming structure used by the theme's
 * rendering engine (for example, since the Bartik theme uses the Twig rendering
 * engine, it overrides the default implementation of the 'page' theme hook by
 * containing a 'page.html.twig' file within its folder structure).
 *
 * @subsection sub_preprocess_templates Preprocessing for Template Files
 * If the implementation is a template file, several functions are called before
 * the template file is invoked to modify the $variables array. These make up
 * the "preprocessing" phase, and are executed (if they exist), in the following
 * order (note that in the following list, HOOK indicates the theme hook name,
 * MODULE indicates a module name, THEME indicates a theme name, and ENGINE
 * indicates a theme engine name):
 * - template_preprocess(&$variables, $hook): Creates a default set of variables
 *   for all theme hooks with template implementations.
 * - template_preprocess_HOOK(&$variables): Should be implemented by the module
 *   that registers the theme hook, to set up default variables.
 * - MODULE_preprocess(&$variables, $hook): hook_preprocess() is invoked on all
 *   implementing modules.
 * - MODULE_preprocess_HOOK(&$variables): hook_preprocess_HOOK() is invoked on
 *   all implementing modules, so that modules that didn't define the theme hook
 *   can alter the variables.
 * - ENGINE_engine_preprocess(&$variables, $hook): Allows the theme engine to
 *   set necessary variables for all theme hooks with template implementations.
 * - ENGINE_engine_preprocess_HOOK(&$variables): Allows the theme engine to set
 *   necessary variables for the particular theme hook.
 * - THEME_preprocess(&$variables, $hook): Allows the theme to set necessary
 *   variables for all theme hooks with template implementations.
 * - THEME_preprocess_HOOK(&$variables): Allows the theme to set necessary
 *   variables specific to the particular theme hook.
 *
 * @subsection sub_preprocess_theme_funcs Preprocessing for Theme Functions
 * If the implementation is a function, only the theme-hook-specific preprocess
 * functions (the ones ending in _HOOK) are called from the list above. This is
 * because theme hooks with function implementations need to be fast, and
 * calling the non-theme-hook-specific preprocess functions for them would incur
 * a noticeable performance penalty.
 *
 * @subsection sub_alternate_suggestions Suggesting Alternate Hooks
 * Alternate hooks can be suggested by implementing the hook-specific
 * hook_theme_suggestions_HOOK_alter() or the generic
 * hook_theme_suggestions_alter(). These alter hooks are used to manipulate an
 * array of suggested alternate theme hooks to use, in reverse order of
 * priority. _theme() will use the highest priority implementation that exists.
 * If none exists, _theme() will use the implementation for the theme hook it
 * was called with. These suggestions are similar to and are used for similar
 * reasons as calling _theme() with an array as the $hook parameter (see below).
 * The difference is whether the suggestions are determined by the code that
 * calls _theme() or by altering the suggestions via the suggestion alter hooks.