Update LMS Help Links

From Peter Desjardins AMA Page:

Q: What procedure should we use to update help links in the LMS over time?

The LMS help links work in the same way that the Studio help links do. A page template defines its online_help_token string. For example, the learner progress page defines that token here:

https://github.com/edx/edx-platform/blob/e5688f6a5ab470a6f8ee1ad3d4e20183c2e8f97d/lms/templates/courseware/progress.html#L3

The lms/templates/navigation.html template includes the help link code, which passes the token string to lms/djangoapps/context_processors.py and common/djangoapps/util/help_context_processor.py which generate the help link URL.

The code in help_context_processor.py reads the components of the URL from docs/lms_config.ini. The base URL is set in the url_base property. The specific doc pages for LMS pages are set in the [pages] section, for example:

https://github.com/edx/edx-platform/blob/master/docs/lms_config.ini#L30

If a template does not define its online_help_token string, the help link on that page will lead to the doc page defined in the default value. In August 2016, there are seven page specific help links, every other page directs to the index page of the learner guide.

To add a new help link to the LMS, do the following.

  1. Find the template for the page in lms/templates. Add a name attribute to the <%def> element. Include a return element including the help token string in the body of the def element. I'm using the Mako template terminology incorrectly. Here's an example:

    <%def name="online_help_token()"><% return "somepage" %></%def>
  2. Add the help token string to the docs/lms_config.ini file, in the [pages] section. Set its value to the page URL path that follows the Read the Docs version. Here's an example:
    somepage = somedirectory/index.html

Notes:

  • There's syntax that will pass an online help token string to the navigation.html from Django templates. Here's an example: https://github.com/edx/edx-platform/blob/master/lms/templates/wiki/base.html#L2. (I notice that there's no page for the wiki defined in the lms_config.ini file.)
  • There's no support for directing help links to different base URLs. So all the links have to go to one document. I initially wanted to direct instructor dashboard pages to the course author's guide, but that level of complexity isn't in the help context processor.
  • The configurable base URL (Open edX docs vs. edX docs) means that each of the LMS page specific doc pages must exist at the same path in both doc sets.