[DEPR]: help-tokens

[sarina]

Proposal Date

2025-04-04

Target Ticket Acceptance Date

2025-04-18

Earliest Open edX Named Release Without This Functionality

Teak 2025-04

Rationale

help-tokens is a package that allows you to switch between pages in different ReadTheDocs books, provided each book has a page of the same name.

Historically, this was done because Open edX and edx.org had different docs books with slightly different text on pages of the same name. However, with the transition to docs.openedx.org, help-tokens no longer works for Open edX docs, rendering links generated by help-tokens to be broken for Open edX users. Further, within the openedx org, only edx-platform uses this package, and seemingly only 16 times, whereas there are nearly 100 direct references to docs links. Keeping this pattern in the codebase will render these docs links broken for Open edX usage. The alternative will be to update help-tokens to work with the new docs.openedx.org URL patterns, which would then break those references to other books. Maintaining this repo is yet another burden on the platform ecosystem.

Removal

help-tokens will be removed for the Teak release, and the 16 usages in edx-platform will be replaced with direct links to Open edX documentation. Note that all other repos (MFEs, etc) already have direct links to documentation only.

Replacement

help-tokens will be removed for the Teak release, and the 16 usages in edx-platform will be replaced with direct links to Open edX documentation.

Deprecation

No response

Migration

No response

Additional Info

If individual installations wish to substitute documentation links with links to their own documentation, work should be done to make links fully configurable. This would involve having a dictionary of some sort in site settings override files that allow you to map a given URL to one of your own choosing. This would be helpful for all kinds of operators, including those that have documentation on sites that are not ReadTheDocs.

An issue has been made here to capture followup work: openedx/openedx-platform#36482

Task List

No response

[jristau1984]

@sarina - Is the target for this DEPR really Teak? That seems really short from acceptance to implementation...

[sarina]

The reason I want to get this into Teak is that it would be a release with broken links.

[jristau1984]

There currently is no replacement solution available, right? This seems contrary to the DEPR practice.

[sarina]

The replacement is directly coding in the links. 86% of the links to docs in the platform are hardcoded links.

[sarina]

I'll also point out this is used 16 times only in edx-platform. There are over 509 hard coded links to the docs sites in other repos. This library is rarely used and is broken in those 16 places

[robrap]

@sarina: Directly coding in the links is not a replacement. It is dropping existing functionality. I agree with @jristau1984 that this feels like it is somewhat overreaching the DEPR process. The process is about removing unneeded code, but at this time, we use this code. Also, you reference the burden of maintaining this repo, but 2U is already signed up to take on this burden.

If there are things that are broken, it does make sense to fix them. If there is a lot of code around this that is not actually used, it may make sense to DEPR/remove that to shrink the problem. It could also make sense to replace the whole system, but only if and when someone is willing to step up and implement the replacement.

[sarina]

Hi @robrap I understand your concern, but my concern is this is very broken and very complicated for little benefit (16 references out of over 500).

What would you think if I removed help-tokens and replaced the 16 references with a settings dictionary, so you could override those 16 links? This would give you greater flexibility to point to docs that aren't sphinx books, ie your help site, etc.

The mapping would be in the django settings:
Something like:

LINK_MAP = {
    'ABOUT': 'https://openedx.org/about',
    'FAQ': 'https://docs.openedx.org/en/latest/faq',
}

then in the places those links are referenced we'd just do a lookup from django settings settings.LINK_MAP['ABOUT'] for example. And then on your installation you could override the settings. And, you could add more mappings to currently-hardcoded links.

[robrap]

@sarina: Thanks. That certainly sounds like a simple replacement.

According to the README help-tokens offers the following benefits:

• Links to custom readthedocs books.
• May use a version setting.
• May use a language setting.

2U doesn't seem to be using the version or language setting. However, if anyone was using these, it seems like they could just update their links accordingly, so I think there wouldn't be any particular loss of functionality with your proposal.

As far as I can tell, the links are defined in the following files:

• https://github.com/openedx/edx-platform/blob/master/lms/envs/help_tokens.ini
• https://github.com/openedx/edx-platform/blob/master/cms/envs/help_tokens.ini
  I see 16 links in the LMS ini (which I think you noted), and another 33 in the CMS ini. Both of these include a default, and I'm not sure all of the places that use the default, and how and if we need to resolve that?

Additionally, your example includes FAQ and ABOUT. I didn't see those in the ini files, so are those examples entirely made up, or am I missing something about the links that are getting updated?

Lastly, there is a question of how to format the settings. I'm ok with the LINK_MAP proposal, however:

• I seem to recall @kdmccormick wishing we flattened all our settings. I'll let Kyle speak for Kyle though.
• We currently have the following settings (not sure if any of these are 2U-only):

ACTIVATION_EMAIL_SUPPORT_LINK
CREDIT_HELP_LINK_URL
ID_VERIFICATION_SUPPORT_LINK
LOGIN_ISSUE_SUPPORT_LINK
PASSWORD_RESET_SUPPORT_LINK
SUPPORT_SITE_LINK
SUPPORT_HOW_TO_UNENROLL_LINK

• Do we want consistency in how we order these and format them, and do we want the old format, the new format, or the old with a prefix that keeps these all together?

[sarina]

Additionally, your example includes FAQ and ABOUT. I didn't see those in the ini files, so are those examples entirely made up, or am I missing something about the links that are getting updated?

Yep those were made-up examples.

Kyle is out today but I'll check with him tomorrow on his thoughts.

I think we likely want consistency in how these are formatted.

[kdmccormick]

I think using Django settings as a replacement for help tokens sounds very reasonable.

I would prefer a flat structure with consistent names over LINK_MAP, because it would make it easy for operators to override individual links using their preferred method (whether that be YAML or Python) without adding any logic to common.py or production.py. If we went with LINK_MAP, we would need to add more specialized override handling to production.py in order to allow YAML users to override individual links rather than the whole LINK_MAP at once.

I'd gently propose LINK_TO_$blah because prefixes are a little easier to search for than suffixes, but $blah_LINK is also very reasonable. Alternatively, if there are existing Django settings to doc pages which are already using an implicit name convention, it could be best to go with that.