Merge pull request #14716 from edx/nedbat/refactor-help-links

An indicator of the Open edX release line, and help tests adapted to same.

common/djangoapps/util/help_context_processor.py

@@ -4,9 +4,11 @@ Online Contextual Help.
 """
 
 import ConfigParser
-from django.conf import settings
 import logging
 
+from django.conf import settings
+
+from openedx.core.release import doc_version
 
 log = logging.getLogger(__name__)
 
@@ -76,7 +78,7 @@ def common_doc_url(request, config_file_object):  # pylint: disable=unused-argum
             return "{url_base}/{language}/{version}/{page_path}".format(
                 url_base=doc_base_url,
                 language=get_config_value_with_default("locales", settings.LANGUAGE_CODE),
-                version=config_file_object.get("help_settings", "version"),
+                version=doc_version(),
                 page_path=get_config_value_with_default("pages", page_token),
             )
 
@@ -102,7 +104,7 @@ def common_doc_url(request, config_file_object):  # pylint: disable=unused-argum
             # Construct and return the URL for the PDF link.
             return "{pdf_base}/{version}/{pdf_file}".format(
                 pdf_base=pdf_base_url,
-                version=config_file_object.get("help_settings", "version"),
+                version=doc_version(),
                 pdf_file=config_file_object.get("pdf_settings", "pdf_file"),
             )
 

common/djangoapps/util/tests/test_help_context_processor.py

@@ -8,6 +8,7 @@ from mock import patch
 from django.conf import settings
 from django.test import TestCase
 
+from openedx.core.release import doc_version
 from util.help_context_processor import common_doc_url
 
 
@@ -33,34 +34,24 @@ class HelpContextProcessorTest(TestCase):
 
     def test_get_doc_url(self):
         # Test default values.
-        self.assertRegexpMatches(
-            self._get_doc_url(),
-            "http://edx.readthedocs.io/projects/open-edx-learner-guide/en/.*/index.html"
-        )
+        doc = "http://edx.readthedocs.io/projects/open-edx-learner-guide/en/{}/index.html"
+        self.assertEqual(self._get_doc_url(), doc.format(doc_version()))
 
         # Provide a known page_token.
-        self.assertRegexpMatches(
-            self._get_doc_url('profile'),
-            "http://edx.readthedocs.io/projects/open-edx-learner-guide/en/.*/sfd_dashboard_profile/index.html"
-        )
+        doc = "http://edx.readthedocs.io/projects/open-edx-learner-guide/en/{}/sfd_dashboard_profile/index.html"
+        self.assertEqual(self._get_doc_url('profile'), doc.format(doc_version()))
 
         # Use settings.DOC_LINK_BASE_URL to override default base_url.
+        doc = "settings_base_url/en/{}/SFD_instructor_dash_help.html"
         with patch('django.conf.settings.DOC_LINK_BASE_URL', 'settings_base_url'):
-            self.assertRegexpMatches(
-                self._get_doc_url('instructor'),
-                "settings_base_url/en/.*/SFD_instructor_dash_help.html"
-            )
+            self.assertEqual(self._get_doc_url('instructor'), doc.format(doc_version()))
 
     def test_get_pdf_url(self):
         # Test default values.
-        self.assertRegexpMatches(
-            self._get_pdf_url(),
-            "https://media.readthedocs.org/pdf/open-edx-learner-guide/.*/open-edx-learner-guide.pdf"
-        )
+        doc = "https://media.readthedocs.org/pdf/open-edx-learner-guide/{}/open-edx-learner-guide.pdf"
+        self.assertEqual(self._get_pdf_url(), doc.format(doc_version()))
 
         # Use settings.DOC_LINK_BASE_URL to override default base_url.
+        doc = "settings_base_url/{}/open-edx-learner-guide.pdf"
         with patch('django.conf.settings.DOC_LINK_BASE_URL', 'settings_base_url'):
-            self.assertRegexpMatches(
-                self._get_pdf_url(),
-                "settings_base_url/.*/open-edx-learner-guide.pdf"
-            )
+            self.assertEqual(self._get_pdf_url(), doc.format(doc_version()))

common/test/acceptance/tests/lms/test_lms_help.py

@@ -3,7 +3,6 @@ Test Help links in LMS
 """
 import json
 
-
 from common.test.acceptance.tests.lms.test_lms_instructor_dashboard import BaseInstructorDashboardTest
 from common.test.acceptance.pages.lms.instructor_dashboard import InstructorDashboardPage
 from common.test.acceptance.tests.studio.base_studio_test import ContainerBase
@@ -15,6 +14,8 @@ from common.test.acceptance.tests.helpers import (
     assert_opened_help_link_is_correct
 )
 
+from openedx.core.release import doc_version
+
 
 class TestCohortHelp(ContainerBase):
     """
@@ -27,16 +28,6 @@ class TestCohortHelp(ContainerBase):
         self.instructor_dashboard_page.visit()
         self.cohort_management = self.instructor_dashboard_page.select_cohort_management()
 
-    def get_url_with_changed_domain(self, url):
-        """
-        Replaces .org with .io in the url
-        Arguments:
-            url (str): The url to perform replace operation on.
-        Returns:
-        str: The updated url
-        """
-        return url.replace('.org/', '.io/')
-
     def verify_help_link(self, href):
         """
         Verifies that help link is correct
@@ -50,7 +41,7 @@ class TestCohortHelp(ContainerBase):
         actual_link = self.cohort_management.get_cohort_help_element_and_click_help()
 
         assert_link(self, expected_link, actual_link)
-        assert_opened_help_link_is_correct(self, self.get_url_with_changed_domain(href))
+        assert_opened_help_link_is_correct(self, href)
 
     def test_manual_cohort_help(self):
         """
@@ -66,8 +57,10 @@ class TestCohortHelp(ContainerBase):
         """
         self.cohort_management.add_cohort('cohort_name')
 
-        href = 'http://edx.readthedocs.org/projects/edx-partner-course-staff/en/latest/' \
-               'course_features/cohorts/cohort_config.html#assign-learners-to-cohorts-manually'
+        href = (
+            'http://edx.readthedocs.io/projects/edx-partner-course-staff/en/{}/'
+            'course_features/cohorts/cohort_config.html#assign-learners-to-cohorts-manually'
+        ).format(doc_version())
 
         self.verify_help_link(href)
 
@@ -86,8 +79,10 @@ class TestCohortHelp(ContainerBase):
 
         self.cohort_management.add_cohort('cohort_name', assignment_type='random')
 
-        href = 'http://edx.readthedocs.org/projects/edx-partner-course-staff/en/latest/' \
-               'course_features/cohorts/cohorts_overview.html#all-automated-assignment'
+        href = (
+            'http://edx.readthedocs.io/projects/edx-partner-course-staff/en/{}/'
+            'course_features/cohorts/cohorts_overview.html#all-automated-assignment'
+        ).format(doc_version())
 
         self.verify_help_link(href)
 
@@ -119,6 +114,8 @@ class InstructorDashboardHelp(BaseInstructorDashboardTest):
         When I click "Help"
         Then I see help about the instructor dashboard in a new tab
         """
-        href = 'http://edx.readthedocs.io/projects/edx-guide-for-students/en/latest/SFD_instructor_dash_help.html'
+        href = (
+            'http://edx.readthedocs.io/projects/edx-guide-for-students/en/{}/SFD_instructor_dash_help.html'
+        ).format(doc_version())
         self.instructor_dashboard_page.click_help()
         assert_opened_help_link_is_correct(self, href)

docs/cms_config.ini

@@ -2,7 +2,6 @@
 [help_settings]
 # The optional DOC_LINK_BASE_URL configuration property will override url_base
 url_base = http://edx.readthedocs.io/projects/open-edx-building-and-running-a-course
-version = latest
 
 
 # below are the pdf settings for the pdf file

docs/lms_config.ini

@@ -2,7 +2,6 @@
 [help_settings]
 # The optional DOC_LINK_BASE_URL configuration property will override url_base
 url_base = http://edx.readthedocs.io/projects/open-edx-learner-guide
-version = latest
 
 
 # below are the pdf settings for the pdf file

lms/templates/instructor/instructor_dashboard_2/cohort-group-header.underscore

@@ -12,10 +12,10 @@
     <div class="setup-value">
         <% if (cohort.get('assignment_type') == "manual") { %>
             <%- gettext("Learners are added to this cohort only when you provide their email addresses or usernames on this page.") %>
-            <a href="http://edx.readthedocs.org/projects/edx-partner-course-staff/en/latest/course_features/cohorts/cohort_config.html#assign-learners-to-cohorts-manually" class="incontext-help action-secondary action-help" target="_blank"><%- gettext("What does this mean?") %></a>
+            <a href="http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/cohorts/cohort_config.html#assign-learners-to-cohorts-manually" class="incontext-help action-secondary action-help" target="_blank"><%- gettext("What does this mean?") %></a>
         <% } else { %>
             <%- gettext("Learners are added to this cohort automatically.") %>
-            <a href="http://edx.readthedocs.org/projects/edx-partner-course-staff/en/latest/course_features/cohorts/cohorts_overview.html#all-automated-assignment" class="incontext-help action-secondary action-help" target="_blank"><%- gettext("What does this mean?") %></a>
+            <a href="http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/cohorts/cohorts_overview.html#all-automated-assignment" class="incontext-help action-secondary action-help" target="_blank"><%- gettext("What does this mean?") %></a>
         <% } %>
     </div>
 </div>

openedx/core/release.py

+"""
+Information about the release line of this Open edX code.
+"""
+
+# The release line: an Open edX release name ("ficus"), or "master".
+# This should always be "master" on the master branch, and will be changed
+# manually when we start release-line branches, like open-release/ficus.master.
+RELEASE_LINE = "master"
+
+
+def doc_version():
+    """The readthedocs.org version name used in documentation references.
+
+    Returns a short string like "latest" or "open-release-ficus.master".
+    """
+    if RELEASE_LINE == "master":
+        return "latest"
+    else:
+        return "open-release-{}.master".format(RELEASE_LINE)