Flexible plugin based help system

Problem/Motivation

#2592487: [meta] Help system overhaul explains a lot of current problems with the help system, which we try to solve in this issue.

Generate overview

Much like menu links, we could move hook_help definitions into a yml file, which looks like the following:

$module.help.yml

module:
  template: help/module.html.twig
other_module_route:
  template: help/other_module_route.html.twig

In each individual template you can then use twig intersected with HTML as you like:

Before

$output = '';
$output .= '<h3>' . t('About') . '</h3>';
$output .= '<p>' . t('The Node module manages the creation, editing, deletion, settings, and display of the main site content. Content items managed by the Node module are typically displayed as pages on your site, and include a title, some meta-data (author, creation time, content type, etc.), and optional fields containing text or other data (fields are managed by the <a href=":field">Field module</a>). For more information, see the <a href=":node">online documentation for the Node module</a>.', array(':node' => 'https://www.drupal.org/documentation/modules/node', ':field' => \Drupal::url('help.page', array('name' => 'field')))) . '</p>';
$output .= '<h3>' . t('Uses') . '</h3>';

After

<h3>{% trans %}About{% endtrans %}</h3>
{# you get the idea #}

## More details.
Internally, much like menu links it could use plugins which would make things easier and more flexible,
as it would enable some of the more tricky usecases.

1. It would also lower the barrier for users with little php knowledge to contribute documentation if they only need to edit a yaml file where it's clearer what's where and how the syntax works.
2. Complex cases:
   There are some weird examples in core:

     if ($route_name != 'node.configure_rebuild_confirm' && $route_name != 'system.batch_page.normal' && $route_name != 'help.page.node' && $route_name != 'help.main'
       && \Drupal::currentUser()->hasPermission('access administration pages') && node_access_needs_rebuild()) {
       if ($route_name == 'system.status') {
         $message = t('The content access permissions need to be rebuilt.');
       }
       else {
         $message = t('The content access permissions need to be rebuilt. <a href=":node_access_rebuild">Rebuild permissions</a>.', array(':node_access_rebuild' => \Drupal::url('node.configure_rebuild_confirm')));
       }
       drupal_set_message($message, 'error');
     }
   

   If you put it into plugins it could do the following:

   node_rebuild:
     class: Drupal\node\Plugin\Help\NodeRebuild
   

   class NodeRebuild {
     public helpHtml() {
       ...
     }
   }
   

3. It allows to write a contrib module that allows to add UI configurable help texts, using derivatives.
4. Cross-linking between help texts could be made easy using a help function help_page('other_name')
5. The plugin discovery could be expanded to core/themes/install profiles, not just modules
6. It addresses the UX problems, given that twig templates are way easier to work with
7. With the yml files you can add additional metadata, like hierarchy information on an additional step.

Addressing points of the meta issue

• [non topical] Each module can only provide one main help page for the admin/help listing

  The plugin based approach allows to add additional metadata later, which for example would allow to introduce topics. This should not be part of the initial issue, but could be added later, with some more planning.

• ] There is no way to search help.

  This is not addressed by this issue. Help is special as it always contains some form of templateing, so a custom search will be needed for every approach.

• [markup] Markup is being provided inside hook_help(), especially for the module help pages, via concatenating translatable strings with HTML tags.

  HTML already has quite some semantic information, like <header>. On top of that proposal though we could introduce .markdown.twig or .restructed_text.twig. This could be done in a follow up. Explictness in templates allows us to deal with that. <3

• [authoring] The current hook_help() syntax is difficult for Documentation writers, who may not be PHP programmers. This is also mentioned as a problem in #2188753: Get rid of hard-coded markup in hook_help() implementations.

  This is addressed by the issue, because yml + twig is way easier than PHP

• [cross-links] There is not a great way to cross-link to other topics. Currently this is done with PHP code (to make sure the other module is enabled) and placeholders for the URLs.

  We could have a custom twig help function: {% help_url('name') %}

• [code] hook_help() is used for two different purposes, and it's kind of a mongrel: the module help pages are specified by responding to a fake path/route, which is a little bit weird. Also, hooks are outdated in general. We have moved many hooks and page generators into plugins, controllers, or YML files.

  We could have different help types, either in one file or in multiple:

  foo:
    type: module
    template: ...
  bar:
    type: route
    route_name: bar
    template: ...
  

• [limited list] There is a core Tour module that provides a different type of help, but tours are not listed on the admin/help page either. Contrib modules may also provide some form of help, but they're not listed either.

  Given the plugin based approach the tour module could integrate with the help system using a custom plugin derivative, which exposes every tour thing and exposes it as a help plugin as well.

• [must enable] There is no way to see the module overview pages without the module being enabled first. This has been filed as a separate issue: #2587469: allow hook_help to run on modules which are not enabled.

  This is not yet enabled by this issue to be honest. Its a tricky problem. There are bits here, for which using twig could help. Linking for example could be wrapped easily.

• [no admin] There is no way for a site builder to add pages to the help, except by writing a module to implement hook_help(). This would still not let them use the Help system to build help pages for content editors or other site users, since it would still be one page per module.

  Using plugin derivatives would allow us to write a config entity based provider one day, with a UI and what not.

• [glossary] It might be useful to have a glossary of terminology that modules/themes could add entries to. This is a separate issue: #2701289: Glossary to extend the Help system

  Not really addressed by this issue. Theoretically this could be just another help type though.

Proposed resolution

Remaining tasks

• Agree on the general direction
• Get approval by help system maintainer
• ...

User interface changes

API changes

Data model changes