Contrib.social

Deprecate hook_help() and combine with Topics

Open on Drupal.org →
Created on 8 February 2019, almost 6 years ago
Updated 17 October 2023, about 1 year ago

Problem/Motivation

If we get #2920309: Add experimental module for Help Topics → committed, and eventually stable, we will have 2 help systems:

a) hook_help(), which has been around since Drupal 4.x, and allows each module to provide 1 module overview topic.
b) Help Topics, which is the new system, and allows core, modules, themes, and profiles each to provide as many topics as they want to.

This will be confusing to users if the two types of topics are in separate places on the main Help page (admin/help), and confusing to developers if they have to support both systems.

Proposed resolution

The goal here is to have just one help system. In order to do that, here are the things we need to do (they can mostly be done simultaneously):

Part 1: Rewrite existing module overview help as topics

1A: Child issue: 📌 [META] Convert hook_help() module overview text to topics Fixed

1B: Closed (outdated): #2687107: Reorganize topics into sensible outline, and/or write more topics → .

Part 2: Decide what to do with the help blocks on admin pages

There are two parts of hook_help() currently. One is for the module overview help pages, which are covered in Part 1. But we also need to figure out what to do with the parts of hook_help() that provide help text that goes into the Help block that can be displayed at the top of admin pages.

If we are going to get rid of this part of hook_help() as well, we will need to figure out how to replace it. TBD.

Part 3: Deal with displaying lingering hook_help() in contrib

Contrib modules will not immediately convert their hook_help() module overview pages to topics. So, we need to figure out how to display them on admin/help. The two possibilities:

a) Leave as-is. Module overviews in a separate section. But this should be moved down under Topics. See also
#2994748: Make a way for Help Page Sections to be ordered →
- And the intro text for this section should link to a how-to for converting to Topics.

b) Make them automagically appear as Topics. Probably they should be put under a top-level topic called something like "Module overviews", with some text explaining that these are left over and maybe a link to how to convert them.

We need to decide which possibility is better. We can start working on this immediately after the initial patch is committed.

Part 4: Deprecate/remove core hook_help()

Once parts 1-3 are done, and the Topics module is otherwise ready to be Stable, we will need a core patch that:
a) Deprecates hook_help() [at least the part that has to do with module overviews -- see also part 2]
b) Removes all the module overview calls from Core hook_help() implementations, and/or the entire hook_help() implementations [depending on step 2]
c) Removes the Coder check and Coding Standard that every module must have a hook_help().
d) Makes the Topics part of help as stable, and makes sure the topics are visible in the Standard install profile.

This part needs to be postponed until parts 1-3 are done, plus the other "ready for stable" stuff is done in the parent roadmap issue.

Remaining tasks

Update the documentation at https://www.drupal.org/docs/8/core/modules/help →

User interface changes

API changes

Data model changes

Release notes snippet

🌱 Plan
Status

Active

Version

11.0 🔥

Component
Help  →

Last updated 12 days ago

No maintainer
Created by

🇺🇸United States jhodgdon Spokane, WA, USA

Live updates comments and jobs are added and updated live.
  • Needs issue summary update

    Issue summaries save everyone time if they are kept up-to-date. See Update issue summary task instructions.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Comment over 1 year ago →
    🇬🇧United Kingdom catch

    Is there an issue somewhere for the help block help, or is this that issue?

  • Comment over 1 year ago →
    🇫🇷France andypost

    I bet this issue is about to deprecate the hook_help() and the help block (help sections are rendered via \Drupal\help\Controller\HelpController::helpMain()), gonna hack on it

  • Comment over 1 year ago →
    🇫🇷France andypost

    Yes, help block needs own issue

  • Comment over 1 year ago →
    🇫🇷France andypost

    First child issue is done, so now waiting to consider help topics stable

  • Comment over 1 year ago →
    🇺🇸United States Amber Himes Matz Portland, OR USA

    Updated issue summary.

  • Comment over 1 year ago →
    🇫🇷France andypost

    This issue will be meta is we consider it actionable, still not clear how properly transition from requiring help topics instead of hook help

    The core's kill-switch for documentation gate in 📌 Move testing of help topic rendering into child of GenericModuleTestBase Active (I re-parented it)

  • Comment over 1 year ago →
    🇫🇷France fgm Paris, France

    FWIW, I tend to use hook_help significantly to document the specific behaviors of modules on various pages. The important point here is that this kind of help is contextual and may contain live data. See for example https://git.drupalcode.org/project/g2/-/blob/8.x-1.x/g2.module#L305 where the help text is complemented by arguments from the current context.

    A nice workaround could be if help topics could receive a context provided by some service, maybe defining injection in the frontmatter.

  • Comment over 1 year ago →
    🇺🇸United States Amber Himes Matz Portland, OR USA

    A nice workaround could be if help topics could receive a context provided by some service, maybe defining injection in the frontmatter.

    I imagine @fgm is not the only one to need this. Sounds like "Allow help topics to get context defined in frontmatter" should be opened as a child issue of this one? @fgm do you want to open the issue, or should I? In either case, I'm interested in more details as to what you are looking for, and if you could provide examples of your modules that use context in their hook_help() implementations. Thank you.

  • Comment over 1 year ago →
    🇫🇷France fgm Paris, France

    @Amber Himes Matz after converting help in G2 help to Help Topics (see https://git.drupalcode.org/project/g2/-/blob/8.x-1.x/g2.module#L305 for the original version, and https://www.drupal.org/files/issues/2023-08-20/3382138.patch → for the converted version, still under review) I'm no longer convinced this is so much needed: a single helper providing access to a \Drupal instance would enable access just about any service by calling all \Drupal static methods as instance methods on that instance, and specifically \Drupal::service()` thus enabling advanced templates to access just about any service without making the frontmatter more complex.

    Still think this is worth a followup ?

  • Comment about 1 year ago →
    🇫🇷France andypost

    Looks it need another yaml file to maintain "binding" of topic to routes and paths at least, like menu system doing for local actions and tasks.

    Other option is contextual module in core which is also using ContextualLinks render element and manager with alter hook

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024