diff --git a/cms/djangoapps/contentstore/context_processors.py b/cms/djangoapps/contentstore/context_processors.py index e9811c8be3..082e52c654 100644 --- a/cms/djangoapps/contentstore/context_processors.py +++ b/cms/djangoapps/contentstore/context_processors.py @@ -1,16 +1,16 @@ - +""" +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) diff --git a/common/djangoapps/util/help_context_processor.py b/common/djangoapps/util/help_context_processor.py new file mode 100644 index 0000000000..5b037d8e13 --- /dev/null +++ b/common/djangoapps/util/help_context_processor.py @@ -0,0 +1,85 @@ +""" +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} diff --git a/docs/config.ini b/docs/cms_config.ini similarity index 100% rename from docs/config.ini rename to docs/cms_config.ini diff --git a/docs/lms_config.ini b/docs/lms_config.ini new file mode 100644 index 0000000000..c5ddfa305e --- /dev/null +++ b/docs/lms_config.ini @@ -0,0 +1,43 @@ +# 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 diff --git a/lms/djangoapps/context_processors.py b/lms/djangoapps/context_processors.py new file mode 100644 index 0000000000..86e47a5b19 --- /dev/null +++ b/lms/djangoapps/context_processors.py @@ -0,0 +1,28 @@ +""" +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) diff --git a/lms/envs/common.py b/lms/envs/common.py index c12fa134dd..791834a369 100644 --- a/lms/envs/common.py +++ b/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 diff --git a/lms/templates/course.html b/lms/templates/course.html index a7f31ba4d3..25f739a8c6 100644 --- a/lms/templates/course.html +++ b/lms/templates/course.html @@ -1,3 +1,4 @@ +<%def name="online_help_token()"><% return "course" %>%def> <%namespace name='static' file='static_content.html'/> <%! from django.utils.translation import ugettext as _ diff --git a/lms/templates/courseware/courseware.html b/lms/templates/courseware/courseware.html index f5a4e90c42..8c4fd74ae3 100644 --- a/lms/templates/courseware/courseware.html +++ b/lms/templates/courseware/courseware.html @@ -1,6 +1,7 @@ <%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 diff --git a/lms/templates/courseware/info.html b/lms/templates/courseware/info.html index d57fbd9d70..93e479bb74 100644 --- a/lms/templates/courseware/info.html +++ b/lms/templates/courseware/info.html @@ -1,5 +1,6 @@ <%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 _ diff --git a/lms/templates/courseware/progress.html b/lms/templates/courseware/progress.html index 43e462f332..e930b1f5fa 100644 --- a/lms/templates/courseware/progress.html +++ b/lms/templates/courseware/progress.html @@ -1,5 +1,6 @@ <%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 diff --git a/lms/templates/dashboard.html b/lms/templates/dashboard.html index ca299fb804..7f0d776144 100644 --- a/lms/templates/dashboard.html +++ b/lms/templates/dashboard.html @@ -1,5 +1,6 @@ <%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 diff --git a/lms/templates/header.html b/lms/templates/header.html index e62672d373..5b07e9f1c7 100644 --- a/lms/templates/header.html +++ b/lms/templates/header.html @@ -1,4 +1,4 @@ ## 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" /> diff --git a/lms/templates/instructor/instructor_dashboard_2/instructor_dashboard_2.html b/lms/templates/instructor/instructor_dashboard_2/instructor_dashboard_2.html index 8a60cc1a04..62974d8d34 100644 --- a/lms/templates/instructor/instructor_dashboard_2/instructor_dashboard_2.html +++ b/lms/templates/instructor/instructor_dashboard_2/instructor_dashboard_2.html @@ -1,5 +1,6 @@ <%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 diff --git a/lms/templates/main.html b/lms/templates/main.html index 9977348fcc..61848b87f2 100644 --- a/lms/templates/main.html +++ b/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
+ <%static:optional_include_mako file="body-initial.html" is_theming_enabled="True" /> % if not disable_window_wrap: @@ -130,7 +132,7 @@ from pipeline_mako import render_require_js_path_overrides ${_("Skip to main content")} % 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