Assuming that #2351991: Replace hook_help() topic pages with config entities gets into Drupal Core, we'll want to convert as many of the existing module help pages to be Topics. This issue is for tracking that. Currently postponed until #2351991: Replace hook_help() topic pages with config entities is finished.
Some concerns:
a) Note that you only can convert the main module overview help page in hook_help() to this new system. The parts of hook_help() that deal with providing page-specific help need to stay in hook_help().
b) If the main module topic is doing something dynamic, that will also need to stay in hook_help(). Only static HTML pages can be converted to the new system.
c) How to do the conversions (in brief):
- Find the hook_help() and the part of it that makes the main module help page.
- Cut this out of the hook_help() implementation. If that makes the implementation empty, delete the whole function.
- Go to admin/config/development/help and click "Add new topic".
- Give it a title of "Foo Bar module", and a machine name of "foo_bar".
- Check the "Top-level topic" box.
- Paste in what you cut from hook_help(). Turn it into pure HTML instead of PHP code.
- Consider adding related topic links to other modules.
- Save.
- Go to admin/help and verify the topic is there. Click through and make sure it looks OK. Edit until it does. It should match what was previously in the help topic page you are converting, with exceptions noted below.
- Use the config export to export the config for this new topic. Save the file as "help.topic.foo_bar.yml" and put it into the core/modules/foo_bar/config/install directory.
- Make a patch to add this file to Core.
d) Inter-topic links -- some of the "dynamic" code in existing hook help is for things like "If the Block module exists, turn this into a link to that module; otherwise make it a dead-ish link." In this case when the help is converted, the suggestion is:
- Take out the link. So the text can still say something about the Block module but it won't be a link.
- Add "block" as a topic in the Related section. If the Block module is enabled, the link will be there. If not, it will be omitted.
e) Related topic links: If module A depends on module B and you think A should be listed as related on B's topic page, then when you are creating the help entity for A, list B in the "List on" section. If you think B should be shown on A's topic page, then when you are creating A, list B directly in the Related section. In this way, only modules that are guaranteed to be turned on should usually be listed within a particular help topic. However, sometimes there will be cases where A and B are related but neither one depends on the other... in this case it is OK to list it on either one, whichever makes the most sense.