Merge pull request #3619 from edx/markhoeber/documentatoin/online-help-system

Online help system

cms/djangoapps/contentstore/context_processors.py

 import ConfigParser
 from django.conf import settings
+import logging
 
+
+log = logging.getLogger(__name__)
+
+
+# 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)
 
 
-def doc_url(request):
-    # in the future, we will detect the locale; for now, we will
-    # hardcode en_us, since we only have English documentation
-    locale = "en_us"
+def doc_url(request=None):  # pylint: disable=unused-argument
+    """
+    This function is added in the list of TEMPLATE_CONTEXT_PROCESSORS, 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.
+    """
+
+    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"),
+            )
 
-    def get_doc_url(token):
-        try:
-            return config.get(locale, token)
-        except ConfigParser.NoOptionError:
-            return config.get(locale, "default")
+        return {
+            "doc_url": get_doc_url(),
+            "pdf_url": get_pdf_url(),
+        }
 
-    return {"doc_url": get_doc_url}
+    return {'get_online_help_info': get_online_help_info}

cms/djangoapps/contentstore/features/course-export.py

-# disable missing docstring
 # pylint: disable=C0111
+# pylint: disable=W0621
+# pylint: disable=W0613
 
 from lettuce import world, step
 from component_settings_editor_helpers import enter_xml_in_advanced_problem
 from nose.tools import assert_true, assert_equal
 
 
-@step('I export the course$')
-def i_export_the_course(step):
+@step('I go to the export page$')
+def i_go_to_the_export_page(step):
     world.click_tools()
     link_css = 'li.nav-course-tools-export a'
     world.css_click(link_css)
+
+
+@step('I export the course$')
+def i_export_the_course(step):
+    step.given('I go to the export page')
     world.css_click('a.action-export')
 
 
@@ -30,7 +36,7 @@ def i_enter_bad_xml(step):
 
 
 @step('I edit and enter an ampersand$')
-def i_enter_bad_xml(step):
+def i_enter_an_ampersand(step):
     enter_xml_in_advanced_problem(step, "<problem>&</problem>")
 
 

cms/djangoapps/contentstore/features/course_import.py

+# pylint: disable=C0111
+# pylint: disable=W0621
+# pylint: disable=W0613
+
 import os
-from lettuce import world
+from lettuce import world, step
 from django.conf import settings
 
 
@@ -14,7 +18,8 @@ def import_file(filename):
     world.css_click(outline_css)
 
 
-def go_to_import():
+@step('I go to the import page$')
+def go_to_import(step):
     menu_css = 'li.nav-course-tools'
     import_css = 'li.nav-course-tools-import a'
     world.css_click(menu_css)

cms/djangoapps/contentstore/features/help.feature

+@shard_1
+Feature: CMS.Help
+    As a course author, I am able to access online help
+
+    Scenario: Users can access online help on course listing page
+        Given There are no courses
+        And I am logged into Studio
+        Then I should see online help for "get_started"
+
+
+    Scenario: Users can access online help within a course
+        Given I have opened a new course in Studio
+
+        And I click the course link in My Courses
+        Then I should see online help for "organizing_course"
+
+        And I go to the course updates page
+        Then I should see online help for "updates"
+
+        And I go to the pages page
+        Then I should see online help for "pages"
+
+        And I go to the files and uploads page
+        Then I should see online help for "files"
+
+        And I go to the textbooks page
+        Then I should see online help for "textbooks"
+
+        And I select Schedule and Details
+        Then I should see online help for "setting_up"
+
+        And I am viewing the grading settings
+        Then I should see online help for "grading"
+
+        And I am viewing the course team settings
+        Then I should see online help for "course-team"
+
+        And I select the Advanced Settings
+        Then I should see online help for "index"
+
+        And I select Checklists from the Tools menu
+        Then I should see online help for "checklist"
+
+        And I go to the import page
+        Then I should see online help for "import"
+
+        And I go to the export page
+        Then I should see online help for "export"
+
+
+    Scenario: Users can access online help on the unit page
+        Given I am in Studio editing a new unit
+        Then I should see online help for "units"
+
+
+    Scenario: Users can access online help on the subsection page
+        Given I have opened a new course section in Studio
+        And I have added a new subsection
+        And I click on the subsection
+        Then I should see online help for "subsections"
+

cms/djangoapps/contentstore/features/help.py

+# pylint: disable=C0111
+# pylint: disable=W0621
+# pylint: disable=W0613
+
+from nose.tools import assert_false  # pylint: disable=no-name-in-module
+from lettuce import step, world
+
+
+@step(u'I should see online help for "([^"]*)"$')
+def see_online_help_for(step, page_name):
+    # make sure the online Help link exists on this page and contains the expected page name
+    elements_found = world.browser.find_by_xpath(
+        '//li[contains(@class, "nav-account-help")]//a[contains(@href, "{page_name}")]'.format(
+            page_name=page_name
+        )
+    )
+    assert_false(elements_found.is_empty())
+
+    # make sure the PDF link on the sock of this page exists
+    # for now, the PDF link stays constant for all the pages so we just check for "pdf"
+    elements_found = world.browser.find_by_xpath(
+        '//section[contains(@class, "sock")]//li[contains(@class, "js-help-pdf")]//a[contains(@href, "pdf")]'
+    )
+    assert_false(elements_found.is_empty())

cms/djangoapps/contentstore/features/problem-editor.py

@@ -6,7 +6,7 @@ from lettuce import world, step
 from nose.tools import assert_equal, assert_true  # pylint: disable=E0611
 from common import type_in_codemirror, open_new_course
 from advanced_settings import change_value
-from course_import import import_file, go_to_import
+from course_import import import_file
 
 DISPLAY_NAME = "Display Name"
 MAXIMUM_ATTEMPTS = "Maximum Attempts"
@@ -218,11 +218,6 @@ def i_have_empty_course(step):
     open_new_course()
 
 
-@step(u'I go to the import page')
-def i_go_to_import(_step):
-    go_to_import()
-
-
 @step(u'I import the file "([^"]*)"$')
 def i_import_the_file(_step, filename):
     import_file(filename)

cms/templates/asset_index.html

 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "files" %></%def>
 <%!
   from django.core.urlresolvers import reverse
   from django.utils.translation import ugettext as _

cms/templates/base.html

@@ -264,7 +264,8 @@
 
     <!-- view -->
     <div class="wrapper wrapper-view">
-      <%include file="widgets/header.html" />
+        <% online_help_token = self.online_help_token() if hasattr(self, 'online_help_token') else None %>
+        <%include file="widgets/header.html" args="online_help_token=online_help_token" />
 
       <div id="page-alert"></div>
 
@@ -276,7 +277,7 @@
       <script type="text/javascript">
         require(['js/sock']);
       </script>
-      <%include file="widgets/sock.html" />
+      <%include file="widgets/sock.html" args="online_help_token=online_help_token" />
       % endif
 
       <%include file="widgets/footer.html" />

cms/templates/checklists.html

 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "checklist" %></%def>
 <%!
   from django.core.urlresolvers import reverse
   from django.utils.translation import ugettext as _

cms/templates/course_info.html

@@ -2,6 +2,7 @@
     from django.utils.translation import ugettext as _
 %>
 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "updates" %></%def>
 <%namespace name='static' file='static_content.html'/>
 
 <!-- TODO decode course # from context_course into title -->

cms/templates/edit-tabs.html

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

cms/templates/edit_subsection.html

 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "subsection" %></%def>
 <%!
   import logging
   from util.date_utils import get_default_time_display, almost_same_datetime

cms/templates/export.html

 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "export" %></%def>
 <%namespace name='static' file='static_content.html'/>
 
 <%!

cms/templates/import.html

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

cms/templates/index.html

 <%! from django.utils.translation import ugettext as _ %>
 
 <%inherit file="base.html" />
-
+<%def name="online_help_token()"><% return "home" %></%def>
 <%block name="title">${_("My Courses")}</%block>
 <%block name="bodyclass">is-signedin index view-dashboard</%block>
 
@@ -275,18 +275,18 @@ require(["domReady!", "jquery", "jquery.form", "js/index"], function(doc, $) {
       % endif
 
     </article>
-
     <aside class="content-supplementary" role="complimentary">
       <div class="bit">
-        <h3 class="title title-3">${_('Need help?')}</h3>
-        <p>${_('If you are new to Studio and having trouble getting started, there are a few things that may be of help:')}</p>
+        <h3 class="title title-3">${_('New to edX Studio?')}</h3>
+        <p>${_('Click Help in the upper-right corner to get more more information about the Studio page you are viewing. You can also use the links at the bottom of the page to access our continously updated documentation and other Studio resources.')}</p>
 
         <ol class="list-actions">
           <li class="action-item">
-            <a href="http://files.edx.org/Getting_Started_with_Studio.pdf" title="This is a PDF Document">${_('Get started by reading Studio\'s Documentation')}</a>
+            
+            <a href="${get_online_help_info(online_help_token())['doc_url']}" target="_blank">${_("Getting Started with edX Studio")}</a>
           </li>
           <li class="action-item">
-            <a href="http://help.edge.edx.org/discussion/new" class="show-tender" title="Use our feedback tool, Tender, to request help">${_('Request help with Studio')}</a>
+            <a href="http://help.edge.edx.org/discussion/new" class="show-tender" title="Use our feedback tool, Tender, to request help">${_('Request help with edX Studio')}</a>
           </li>
         </ol>
       </div>

cms/templates/manage_users.html

@@ -4,6 +4,7 @@
 <%! from student.roles import CourseInstructorRole %>
 <%! from xmodule.modulestore.django import loc_mapper %>
 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "team" %></%def>
 <%block name="title">${_("Course Team Settings")}</%block>
 <%block name="bodyclass">is-signedin course users view-team</%block>
 

cms/templates/overview.html

 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "outline" %></%def>
 <%!
   import logging
   from util.date_utils import get_default_time_display

cms/templates/settings.html

 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "schedule" %></%def>
 <%block name="title">${_("Schedule &amp; Details Settings")}</%block>
 <%block name="bodyclass">is-signedin course schedule view-settings feature-upload</%block>
 

cms/templates/settings_advanced.html

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

cms/templates/settings_graders.html

 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "grading" %></%def>
 <%block name="title">${_("Grading Settings")}</%block>
 <%block name="bodyclass">is-signedin course grading view-settings</%block>
 

cms/templates/textbooks.html

 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "textbooks" %></%def>
 <%namespace name='static' file='static_content.html'/>
 <%! import json %>
 <%! from django.utils.translation import ugettext as _ %>
@@ -74,6 +75,7 @@ require(["js/models/section", "js/collections/textbook", "js/views/list_textbook
         <div class="bit">
           <h3 class="title-3">${_("What if my book isn't divided into chapters?")}</h3>
           <p>${_("If your textbook doesn't have individual chapters, you can upload the entire text as a single chapter and enter a name of your choice in the Chapter Name field.")}</p>
+          <p><a href="${get_online_help_info(online_help_token())['doc_url']}" target="_blank">${_("Learn More")}</a></p>
         </div>
       </aside>
     </section>

cms/templates/unit.html

 <%inherit file="base.html" />
+<%def name="online_help_token()"><% return "unit" %></%def>
 <%!
 from django.core.urlresolvers import reverse
 from contentstore.views.helpers import EDITING_TEMPLATES

cms/templates/widgets/header.html

@@ -3,7 +3,9 @@
   from django.core.urlresolvers import reverse
   from django.utils.translation import ugettext as _
   from xmodule.modulestore.django import loc_mapper
+  from contentstore.context_processors import doc_url
 %>
+<%page args="online_help_token"/>
 
 <div class="wrapper-header wrapper" id="view-top">
   <header class="primary" role="banner">
@@ -122,26 +124,9 @@
       % if user.is_authenticated():
       <nav class="nav-account nav-is-signedin nav-dd ui-right">
         <h2 class="sr">${_("Help &amp; Account Navigation")}</h2>
-
         <ol>
           <li class="nav-item nav-account-help">
-            <h3 class="title"><span class="label">${_("Help")}</span> <i class="icon-caret-down ui-toggle-dd"></i></h3>
-
-            <div class="wrapper wrapper-nav-sub">
-              <div class="nav-sub">
-                <ul>
-                  <li class="nav-item nav-help-documentation">
-                    <a href="http://files.edx.org/Getting_Started_with_Studio.pdf" title="${_("This is a PDF Document")}">${_("Studio Documentation")}</a>
-                  </li>
-                  <li class="nav-item nav-help-helpcenter">
-                    <a href="http://help.edge.edx.org/" rel="external">${_("Studio Help Center")}</a>
-                  </li>
-                  <li class="nav-item nav-help-feedback">
-                    <a href="http://help.edge.edx.org/discussion/new" class="show-tender" title="${_("Use our feedback tool, Tender, to share your feedback")}">${_("Contact Us")}</a>
-                  </li>
-                </ul>
-              </div>
-            </div>
+            <h3 class="title"><span class="label"><a href="${get_online_help_info(online_help_token)['doc_url']}" title="${_("Contextual Online Help")}" target="${_("_blank")}">${_("Help")}</a></span></h3>
           </li>
 
           <li class="nav-item nav-account-user">

cms/templates/widgets/sock.html

 <%! from django.utils.translation import ugettext as _ %>
 <%! from django.core.urlresolvers import reverse %>
+<%page args="online_help_token"/>
 <div class="wrapper-sock wrapper">
   <ul class="list-actions list-cta">
     <li class="action-item">
-      <a href="#sock" class="cta cta-show-sock"><i class="icon-question-sign"></i> <span class="copy">${_("Looking for Help with Studio?")}</span></a>
+      <a href="#sock" class="cta cta-show-sock"><i class="icon-question-sign"></i> <span class="copy">${_("Looking for help with Studio?")}</span></a>
     </li>
   </ul>
 
   <div class="wrapper-inner wrapper">
     <section class="sock" id="sock">
       <header>
-        <h2 class="title sr">${_("edX Studio Help")}</h2>
+        <h2 class="title sr">${_("edX Studio Documentation")}</h2>
       </header>
 
       <div class="support">
-        <h3 class="title">${_("Studio Support")}</h3>
+        <h3 class="title">${_("edX Studio Documentation")}</h3>
 
         <div class="copy">
-           <p>${_("Need help with Studio? Creating a course is complex, so we're here to help. Take advantage of our documentation, help center, as well as our edX101 introduction course for course authors.")}</p>
+           <p>${_("You can click Help in the upper right corner of any page to get more information about the page you're on. You can also use the links below to download the Building and Running an edX Course PDF file, to go to the edX Author Support site, or to enroll in edX101.")}</p>
         </div>
 
       <ul class="list-actions">
+          <li class="action-item js-help-pdf">
+            <a href="${get_online_help_info(online_help_token)['pdf_url']}" target="_blank" rel="external" class="action action-primary">${_("Building and Running an edX Course PDF")}</a>
+          </li>
+
         <li class="action-item">
-          <a href="http://files.edx.org/Getting_Started_with_Studio.pdf" class="action action-primary" title="${_("This is a PDF Document")}">${_("Download Studio Documentation")}</a>
-          <span class="tip">${_("How to use Studio to build your course")}</span>
-        </li>
-        <li class="action-item">
-          <a href="http://help.edge.edx.org/" rel="external" class="action action-primary">${_("Studio Help Center")}</a>
-          <span class="tip">${_("Studio Help Center")}</span>
+          <a href="http://help.edge.edx.org/" rel="external" class="action action-primary">${_("edX Studio Author Support")}</a>
+          <span class="tip">${_("edX Studio Author Support")}</span>
         </li>
         <li class="action-item">
           <a href="https://edge.edx.org/courses/edX/edX101/How_to_Create_an_edX_Course/about" rel="external" class="action action-primary">${_("Enroll in edX101")}</a>
-          <span class="tip">${_("How to use Studio to build your course")}</span>
+          <span class="tip">${_("How to use edX Studio to build your course")}</span>
         </li>
       </ul>
       </div>
 
       <div class="feedback">
-        <h3 class="title">${_("Contact us about Studio")}</h3>
+        <h3 class="title">${_("Request help with edX Studio")}</h3>
 
         <div class="copy">
-           <p>${_("Have problems, questions, or suggestions about Studio? We're also here to listen to any feedback you want to share.")}</p>
+           <p>${_("Have problems, questions, or suggestions about edX Studio?")}</p>
         </div>
 
         <ul class="list-actions">

docs/config.ini

-[en_us]
-default=default
+# below are the server-wide settings for documentation
+[help_settings]
+url_base = http://edx.readthedocs.org/projects/edx-partner-course-staff
+version = latest
+
+
+# below are the pdf settings for the pdf file
+[pdf_settings]
+pdf_base = https://media.readthedocs.org/pdf/edx-partner-course-staff
+pdf_file = edx-partner-course-staff.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
+home = getting_started/get_started.html
+outline = creating_content/organizing_course.html
+subsection = creating_content/organizing_course.html#subsections
+unit = creating_content/organizing_course.html#units
+updates = creating_content/handouts_updates.html
+pages = creating_content/pages.html
+files = creating_content/course_files.html
+textbooks = creating_content/textbooks.html
+schedule = building_course/setting_up_student_view.html
+grading = building_course/establish_grading_policy.html
+team = building_course/creating_new_course.html#add-course-team-members
+advanced = index.html
+checklist = building_course/creating_new_course.html#use-the-course-checklist
+import = building_course/export_import_course.html#import-a-course
+export = building_course/export_import_course.html#export-a-course
+
+# below are the language directory names for the different locales
+[locales]
+default = en
+en = en
+en_us = en
\ No newline at end of file