Consider leveraging help topics for module documentation

Problem/Motivation

Following up from this "Inline user guides" forum topic: https://farmos.discourse.group/t/inline-user-guides/680

I'd like to propose we leverage the Drupal core help and help_topics modules for providing this kind of self-hosted inline user guide for farmOS.

Some core documentation on help topics: https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... →

Features of this approach:

• help module provides an existing "HelpSection" plugin + UI
• help_topics module provides a frame work for providing individual help topics plugins via twig files or php classes
• Version controlled
• Self hosted docs
• Translated via localize.drupal.org
• Contrib modules can provide docs
• Individual help topics can be considered "top-level" to display within the Help section
• Help topics can specify "related topics" whose links are included below (bi-directional relationship, related topics are displayed on both pages)
• Help topic twig files could (in theory) be parsed and pulled into farmOS.org docs, potentially pull translations from localize.drupal.org

I've attached a screenshot of what the /admin/help page looks like with the help_topics module enabled. The core help module is what enables this page itself as well as the "Module overview" section on the bottom. The help_topics module provides the "Topics" section and is designed to be a layer above the simple "module overview", similar (as I understand) to our farmOS user guide. These help topics can be provided by any module, and only the "top-level" topics are displayed within this "Topics" section. Individual topics can also specify "related topics" that are rendered (bi-directionally) as links at the bottom of a topic page.

Without any custom code farmOS could simply add some top-level topics that would be displayed in this "Topics" section. But it would be ideal if farmOS topics could have their own section, since only site admins need to see these other Drupal topics. In my investigation I found it's simple to create additional sections - in the screenshot I included an additional "Farm topics" section. This is where dedicated farmOS help topics could be displayed!

The missing link is trying to leverage the existing help_topics framework, but put them in our own dedicated section. I actually chatted with @jhodgdon in the Spokane drupal meetup for ideas on this. We might be able to extend the help_topics HelpSection plugin itself and/or implement some alter hooks to change which help topics end up being displayed in the farmOS section. OR it might be easier to go a step further and extend the help topics plugin + discovery to check for help topics in a dedicated farm_help_topics directory. This way we'd have more control with our own plugin, but be inheriting the core help_topics features. ***errr this might break translations on localize.drupal.org though.

Also notable is this "config help" sandbox project from @jhodgdon (might not be working at the moment): https://www.drupal.org/sandbox/jhodgdon/2369943 → Originally the help_topics module was going to use config entities, but they decided against it because config entities are not forced to say in-sync with the source code (site admins would have to update the config after changes). Makes sense, and inline with our desire for version controlled docs! But help topics as config is generally interesting as well - a farm manager could create dedicated help topics for tasks on the farm that workers could reference... :-)

Steps to reproduce

N/A

Proposed resolution

• Extend & reuse the help_topics plugin manager to load "Farm help topics" from a dedicated farm_help_topics directory within each module.
• Create a new "farmOS Topics" help topic section (see screenshot for simple example). Display all top-level "Farm help topics" inside this section.

Remaining tasks

Decide on an approach. Figure out if translations would work in our own directory. Implement! And provide docs :-)

User interface changes

Inline user guides/module documentation available from the farmOS UI. At /admin/help and/or dedicated menu/toolbar items?

API changes

New "farm help topics" plugin.

Data model changes

None.