Merge pull request #11703 from edx/docs/context-help

LMS Online Contextual Help

cms/djangoapps/contentstore/context_processors.py

-
+"""
+Django Template Context Processor for CMS Online Contextual Help
+"""
 import ConfigParser
 from django.conf import settings
-import logging
-
 
-log = logging.getLogger(__name__)
+from util.help_context_processor import common_doc_url
 
 
 # Open and parse the configuration file when the module is initialized
-config_file = open(settings.REPO_ROOT / "docs" / "config.ini")
-config = ConfigParser.ConfigParser()
-config.readfp(config_file)
+CONFIG_FILE = open(settings.REPO_ROOT / "docs" / "cms_config.ini")
+CONFIG = ConfigParser.ConfigParser()
+CONFIG.readfp(CONFIG_FILE)
 
 
 def doc_url(request=None):  # pylint: disable=unused-argument
@@ -25,60 +25,4 @@ def doc_url(request=None):  # pylint: disable=unused-argument
         request: Currently not used, but is passed by django to context processors.
             May be used in the future for determining the language of choice.
     """
-
-    def get_online_help_info(page_token=None):
-        """
-        Args:
-            page_token: A string that identifies the page for which the help information is requested.
-                It should correspond to an option in the docs/config.ini file.  If it doesn't, the "default"
-                option is used instead.
-
-        Returns:
-            A dict mapping the following items
-                * "doc_url" - a string with the url corresponding to the online help location for the given page_token.
-                * "pdf_url" - a string with the url corresponding to the location of the PDF help file.
-        """
-
-        def get_config_value_with_default(section_name, option, default_option="default"):
-            """
-            Args:
-                section_name: name of the section in the configuration from which the option should be found
-                option: name of the configuration option
-                default_option: name of the default configuration option whose value should be returned if the
-                    requested option is not found
-            """
-            try:
-                return config.get(section_name, option)
-            except (ConfigParser.NoOptionError, AttributeError):
-                log.debug("Didn't find a configuration option for '%s' section and '%s' option", section_name, option)
-                return config.get(section_name, default_option)
-
-        def get_doc_url():
-            """
-            Returns:
-                The URL for the documentation
-            """
-            return "{url_base}/{language}/{version}/{page_path}".format(
-                url_base=config.get("help_settings", "url_base"),
-                language=get_config_value_with_default("locales", settings.LANGUAGE_CODE),
-                version=config.get("help_settings", "version"),
-                page_path=get_config_value_with_default("pages", page_token),
-            )
-
-        def get_pdf_url():
-            """
-            Returns:
-                The URL for the PDF document using the pdf_settings and the help_settings (version) in the configuration
-            """
-            return "{pdf_base}/{version}/{pdf_file}".format(
-                pdf_base=config.get("pdf_settings", "pdf_base"),
-                version=config.get("help_settings", "version"),
-                pdf_file=config.get("pdf_settings", "pdf_file"),
-            )
-
-        return {
-            "doc_url": get_doc_url(),
-            "pdf_url": get_pdf_url(),
-        }
-
-    return {'get_online_help_info': get_online_help_info}
+    return common_doc_url(request, CONFIG)

common/djangoapps/util/help_context_processor.py

+"""
+Common functionality for Django Template Context Processor for
+Online Contextual Help.
+"""
+
+import ConfigParser
+from django.conf import settings
+import logging
+
+
+log = logging.getLogger(__name__)
+
+
+def common_doc_url(request, config_file_object):  # pylint: disable=unused-argument
+    """
+    This function is added in the list of TEMPLATES 'context_processors' OPTION, which is a django setting for
+    a tuple of callables that take a request object as their argument and return a dictionary of items
+    to be merged into the RequestContext.
+
+    This function returns a dict with get_online_help_info, making it directly available to all mako templates.
+
+    Args:
+        request: Currently not used, but is passed by django to context processors.
+            May be used in the future for determining the language of choice.
+        config_file_object: Configuration file object.
+    """
+
+    def get_online_help_info(page_token=None):
+        """
+        Args:
+            page_token: A string that identifies the page for which the help information is requested.
+                It should correspond to an option in the docs/config_file_object.ini file.  If it doesn't, the "default"
+                option is used instead.
+
+        Returns:
+            A dict mapping the following items
+                * "doc_url" - a string with the url corresponding to the online help location for the given page_token.
+                * "pdf_url" - a string with the url corresponding to the location of the PDF help file.
+        """
+
+        def get_config_value_with_default(section_name, option, default_option="default"):
+            """
+            Args:
+                section_name: name of the section in the configuration from which the option should be found
+                option: name of the configuration option
+                default_option: name of the default configuration option whose value should be returned if the
+                    requested option is not found
+            """
+            if option:
+                try:
+                    return config_file_object.get(section_name, option)
+                except (ConfigParser.NoOptionError, AttributeError):
+                    log.debug("Didn't find a configuration option for '%s' section and '%s' option",
+                              section_name, option)
+            return config_file_object.get(section_name, default_option)
+
+        def get_doc_url():
+            """
+            Returns:
+                The URL for the documentation
+            """
+            return "{url_base}/{language}/{version}/{page_path}".format(
+                url_base=config_file_object.get("help_settings", "url_base"),
+                language=get_config_value_with_default("locales", settings.LANGUAGE_CODE),
+                version=config_file_object.get("help_settings", "version"),
+                page_path=get_config_value_with_default("pages", page_token),
+            )
+
+        def get_pdf_url():
+            """
+            Returns:
+                The URL for the PDF document using the pdf_settings and the help_settings (version) in the configuration
+            """
+            return "{pdf_base}/{version}/{pdf_file}".format(
+                pdf_base=config_file_object.get("pdf_settings", "pdf_base"),
+                version=config_file_object.get("help_settings", "version"),
+                pdf_file=config_file_object.get("pdf_settings", "pdf_file"),
+            )
+
+        return {
+            "doc_url": get_doc_url(),
+            "pdf_url": get_pdf_url(),
+        }
+
+    return {'get_online_help_info': get_online_help_info}

docs/lms_config.ini

+# below are the server-wide settings for documentation
+[help_settings]
+url_base = http://edx.readthedocs.io/projects/open-edx-learner-guide
+version = latest
+
+
+# below are the pdf settings for the pdf file
+[pdf_settings]
+pdf_base = https://media.readthedocs.io/pdf/open-edx-learner-guide
+pdf_file = open-edx-learner-guide.pdf
+
+
+# below are the sub-paths to the documentation for the various pages
+# NOTE: If any of these page settings change, then their corresponding test should be updated
+#       in edx-platform/cms/djangoapps/contentstore/features/help.feature
+[pages]
+default = index.html
+
+
+instructor = set_up_course/creating_course_certificates.html
+
+course = set_up_course/creating_course_certificates.html
+
+profile = sfd_dashboard_profile/index.html
+
+dashboard = sfd_dashboard_profile/index.html
+
+courseinfo = SFD_introduction.html
+
+progress = SFD_check_progress.html
+
+learneraccountsettings = sfd_dashboard_profile/SFD_dashboard_settings_profile.html#exploring-the-account-settings-page
+
+learnerdashboard = sfd_dashboard_profile/SFD_dashboard_settings_profile.html#exploring-the-learner-dashboard
+
+bookmarks = SFD_bookmarks.html
+
+
+# below are the language directory names for the different locales
+[locales]
+default = en
+en = en
+en_us = en

lms/djangoapps/context_processors.py

+"""
+Django Template Context Processor for LMS Online Contextual Help
+"""
+import ConfigParser
+from django.conf import settings
+
+from util.help_context_processor import common_doc_url
+
+
+# Open and parse the configuration file when the module is initialized
+CONFIG_FILE = open(settings.REPO_ROOT / "docs" / "lms_config.ini")
+CONFIG = ConfigParser.ConfigParser()
+CONFIG.readfp(CONFIG_FILE)
+
+
+def doc_url(request=None):  # pylint: disable=unused-argument
+    """
+    This function is added in the list of TEMPLATES 'context_processors' OPTION, which is a django setting for
+    a tuple of callables that take a request object as their argument and return a dictionary of items
+    to be merged into the RequestContext.
+
+    This function returns a dict with get_online_help_info, making it directly available to all mako templates.
+
+    Args:
+        request: Currently not used, but is passed by django to context processors.
+            May be used in the future for determining the language of choice.
+    """
+    return common_doc_url(request, CONFIG)

lms/envs/common.py

@@ -514,6 +514,9 @@ TEMPLATES = [
 
                 # Allows the open edX footer to be leveraged in Django Templates.
                 'edxmako.shortcuts.microsite_footer_context_processor',
+
+                # Online contextual help
+                'context_processors.doc_url',
             ],
             # Change 'debug' in your environment settings files - not here.
             'debug': False

lms/templates/course.html

+<%def name="online_help_token()"><% return "course" %></%def>
 <%namespace name='static' file='static_content.html'/>
 <%!
 from django.utils.translation import ugettext as _

lms/templates/courseware/courseware.html

 <%page expression_filter="h"/>
 <%inherit file="/main.html" />
 <%namespace name='static' file='/static_content.html'/>
+<%def name="online_help_token()"><% return "courseware" %></%def>
 <%!
 from django.utils.translation import ugettext as _
 from django.conf import settings

lms/templates/courseware/info.html

 <%page expression_filter="h"/>
 <%inherit file="../main.html" />
+<%def name="online_help_token()"><% return "courseinfo" %></%def>
 <%namespace name='static' file='../static_content.html'/>
 <%!
 from django.utils.translation import ugettext as _

lms/templates/courseware/progress.html

 <%inherit file="/main.html" />
 <%namespace name='static' file='/static_content.html'/>
+<%def name="online_help_token()"><% return "progress" %></%def>
 <%!
 from django.utils.translation import ugettext as _
 from django.core.urlresolvers import reverse

lms/templates/dashboard.html

 <%page expression_filter="h"/>
 <%inherit file="main.html" />
+<%def name="online_help_token()"><% return "learnerdashboard" %></%def>
 <%namespace name='static' file='static_content.html'/>
 <%!
 from django.core.urlresolvers import reverse

lms/templates/header.html

 ## mako
-<%page expression_filter="h"/>
+<%page expression_filter="h" args="online_help_token"/>
 <%namespace name='static' file='static_content.html'/>
-<%include file="${static.get_themed_template_path(relative_path='theme-header.html', default_path='navigation.html')}" />
+<%include file="${static.get_themed_template_path(relative_path='theme-header.html', default_path='navigation.html')}"  args="online_help_token=online_help_token"  />

lms/templates/instructor/instructor_dashboard_2/instructor_dashboard_2.html

 <%inherit file="/main.html" />
 <%namespace name='static' file='/static_content.html'/>
+<%def name="online_help_token()"><% return "instructor" %></%def>
 <%!
 from django.utils.translation import ugettext as _
 from django.core.urlresolvers import reverse

lms/templates/main.html

@@ -11,6 +11,7 @@
 
 
 <%namespace name='static' file='static_content.html'/>
+<% online_help_token = self.online_help_token() if hasattr(self, 'online_help_token') else None %>
 <%!
 from django.core.urlresolvers import reverse
 from django.utils.http import urlquote_plus
@@ -122,6 +123,7 @@ from pipeline_mako import render_require_js_path_overrides
 </head>
 
 <body class="${static.dir_rtl()} <%block name='bodyclass'/> lang_${LANGUAGE_CODE}">
+
 <%static:optional_include_mako file="body-initial.html" is_theming_enabled="True" />
 <div id="page-prompt"></div>
 % if not disable_window_wrap:
@@ -130,7 +132,7 @@ from pipeline_mako import render_require_js_path_overrides
     <a class="nav-skip" href="#main">${_("Skip to main content")}</a>
 
     % if not disable_header:
-        <%include file="${static.get_template_path('header.html')}" />
+        <%include file="${static.get_template_path('header.html')}" args="online_help_token=online_help_token" />
     % endif
 
     <div class="content-wrapper" id="content">

lms/templates/main_django.html

@@ -30,7 +30,7 @@
   <div class="window-wrap" dir="{{LANGUAGE_BIDI|yesno:'rtl,ltr'}}">
     <a class="nav-skip" href="#main">{% trans "Skip to main content" %}</a>
     {% with course=request.course %}
-      {% include "header.html"|microsite_template_path %}
+      {% include "header.html"|microsite_template_path with online_help_token=online_help_token  %}
     {% endwith %}
     <div class="content-wrapper" id="content">
       {% block body %}{% endblock %}

lms/templates/navigation.html

 ## mako
-<%page expression_filter="h"/>
+<%page expression_filter="h" args="online_help_token"/>
 <%namespace name='static' file='static_content.html'/>
 <%namespace file='main.html' import="login_query"/>
 <%!
 from django.core.urlresolvers import reverse
 from django.utils.translation import ugettext as _
 
+from context_processors import doc_url
 from lms.djangoapps.ccx.overrides import get_current_ccx
 from microsite_configuration import microsite
 from microsite_configuration.templatetags.microsite import platform_name

lms/templates/student_account/account_settings.html

@@ -13,6 +13,7 @@ from openedx.core.djangolib.js_utils import dump_js_escaped_json, js_escaped_str
 <!--<%namespace name='static' file='/static_content.html'/>-->
 
 <%inherit file="/main.html" />
+<%def name="online_help_token()"><% return "learneraccountsettings" %></%def>
 <%namespace name='static' file='/static_content.html'/>
 
 <%block name="pagetitle">${_("Account Settings")}</%block>

lms/templates/student_profile/learner_profile.html

 <%page expression_filter="h"/>
 <%inherit file="/main.html" />
+<%def name="online_help_token()"><% return "profile" %></%def>
 <%namespace name='static' file='/static_content.html'/>
 <%!
 import json

lms/templates/wiki/base.html

 {% extends "main_django.html" %}
+{% with online_help_token="wiki" %}
 {% load pipeline %}{% load sekizai_tags i18n microsite %}{% load url from future %}{% load staticfiles %}
 
 {% block title %}<title>{% block pagetitle %}{% endblock %} | {% trans "Wiki" %} | {% platform_name %}</title>{% endblock %}
@@ -78,3 +79,4 @@
 </main>
 
 {% endblock %}
+{% endwith %}