From c8911b628279329a7cfe8cba819621bedc4eaa93 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9gis=20Behmo?= <regis@behmo.com>
Date: Wed, 19 Aug 2020 22:27:09 +0200
Subject: [PATCH] Document lms/djangoapps/course_api feature toggles

---
 lms/djangoapps/course_api/__init__.py       |  28 +++
 lms/djangoapps/course_api/blocks/toggles.py |  25 +-
 lms/envs/common.py                          | 256 ++++++++------------
 3 files changed, 146 insertions(+), 163 deletions(-)

diff --git a/lms/djangoapps/course_api/__init__.py b/lms/djangoapps/course_api/__init__.py
index 790a495b4ea..1ea4abdb5ee 100644
--- a/lms/djangoapps/course_api/__init__.py
+++ b/lms/djangoapps/course_api/__init__.py
@@ -5,5 +5,33 @@ from openedx.core.djangoapps.waffle_utils import WaffleSwitch, WaffleSwitchNames
 
 WAFFLE_SWITCH_NAMESPACE = WaffleSwitchNamespace(name='course_list_api_rate_limit')
 
+"""
+.. toggle_name: course_list_api_rate_limit.rate_limit_2
+.. toggle_implementation: WaffleSwitch
+.. toggle_default: False
+.. toggle_description: Waffle switch to enable the throttling of 2 requests/minute to
+  the course API. For staff users, this limit is 10 requests/minute.
+.. toggle_category: course_api
+.. toggle_use_cases: open_edx
+.. toggle_creation_date: 2018-06-12
+.. toggle_expiration_date: None
+.. toggle_warnings: None
+.. toggle_tickets: https://openedx.atlassian.net/browse/LEARNER-5527
+.. toggle_status: supported
+"""
 USE_RATE_LIMIT_2_FOR_COURSE_LIST_API = WaffleSwitch(WAFFLE_SWITCH_NAMESPACE, 'rate_limit_2', __name__)
+"""
+.. toggle_name: course_list_api_rate_limit.rate_limit_10
+.. toggle_implementation: WaffleSwitch
+.. toggle_default: False
+.. toggle_description: Waffle switch to enable the throttling of 10 requests/minute to
+  the course API. For staff users, this limit is 20 requests/minute.
+.. toggle_category: course_api
+.. toggle_use_cases: open_edx
+.. toggle_creation_date: 2018-06-12
+.. toggle_expiration_date: None
+.. toggle_warnings: None
+.. toggle_tickets: https://openedx.atlassian.net/browse/LEARNER-5527
+.. toggle_status: supported
+"""
 USE_RATE_LIMIT_10_FOR_COURSE_LIST_API = WaffleSwitch(WAFFLE_SWITCH_NAMESPACE, 'rate_limit_10', __name__)
diff --git a/lms/djangoapps/course_api/blocks/toggles.py b/lms/djangoapps/course_api/blocks/toggles.py
index 6ca707d3ae7..aae9ae12d67 100644
--- a/lms/djangoapps/course_api/blocks/toggles.py
+++ b/lms/djangoapps/course_api/blocks/toggles.py
@@ -8,18 +8,19 @@ from openedx.core.djangoapps.waffle_utils import CourseWaffleFlag, WaffleFlag, W
 
 COURSE_BLOCKS_API_NAMESPACE = WaffleFlagNamespace(name=u'course_blocks_api')
 
-# Waffle flag to hide access denial message.
-# .. toggle_name: course_blocks_api.hide_access_denials
-# .. toggle_implementation: WaffleFlag
-# .. toggle_default: False
-# .. toggle_description: ??
-# .. toggle_category: course api
-# .. toggle_use_cases: incremental_release, open_edx
-# .. toggle_creation_date: 2019-04-10
-# .. toggle_expiration_date: ??
-# .. toggle_warnings: ??
-# .. toggle_tickets: ??
-# .. toggle_status: ??
+"""
+.. toggle_name: course_blocks_api.hide_access_denials
+.. toggle_implementation: WaffleFlag
+.. toggle_default: False
+.. toggle_description: Waffle flag to hide access denial messages in the course blocks.
+.. toggle_category: course api
+.. toggle_use_cases: incremental_release, open_edx
+.. toggle_creation_date: ??
+.. toggle_expiration_date: None
+.. toggle_warnings: None
+.. toggle_tickets: ??
+.. toggle_status: supported
+"""
 HIDE_ACCESS_DENIALS_FLAG = WaffleFlag(
     waffle_namespace=COURSE_BLOCKS_API_NAMESPACE,
     flag_name=u'hide_access_denials',
diff --git a/lms/envs/common.py b/lms/envs/common.py
index 06ccd3a8dfe..fd995fdfc64 100644
--- a/lms/envs/common.py
+++ b/lms/envs/common.py
@@ -100,42 +100,30 @@ FEATURES = {
     # this should remain off in production until digest notifications are online.
     'ENABLE_DISCUSSION_HOME_PANEL': False,
 
-    """
-    .. toggle_name: ENABLE_DISCUSSION_EMAIL_DIGEST
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: False
-    .. toggle_description: Set this to True if you want the discussion digest emails
-      enabled automatically for new users. This will be set on all new account
-      registrations.
-    .. toggle_category: admin
-    .. toggle_use_cases: open_edx
-    .. toggle_creation_date: 2014-08-19
-    .. toggle_expiration_date: None
-    .. toggle_warnings: It is not recommended to enable this feature if
-      ENABLE_DISCUSSION_HOME_PANEL is not enabled, since subscribers who receive
-      digests in that case will only be able to unsubscribe via links embedded
-      in their emails, and they will have no way to resubscribe.
-    .. toggle_tickets: https://github.com/edx/edx-platform/pull/4891
-    .. toggle_status: supported
-    """
+    # .. toggle_name: ENABLE_DISCUSSION_EMAIL_DIGEST
+    # .. toggle_implementation: DjangoSetting
+    # .. toggle_default: False
+    # .. toggle_description: Set this to True if you want the discussion digest emails enabled automatically for new users. This will be set on all new account registrations.
+    # .. toggle_category: admin
+    # .. toggle_use_cases: open_edx
+    # .. toggle_creation_date: 2014-08-19
+    # .. toggle_expiration_date: None
+    # .. toggle_warnings: It is not recommended to enable this feature if ENABLE_DISCUSSION_HOME_PANEL is not enabled, since subscribers who receive digests in that case will only be able to unsubscribe via links embedded in their emails, and they will have no way to resubscribe.
+    # .. toggle_tickets: https://github.com/edx/edx-platform/pull/4891
+    # .. toggle_status: supported
     'ENABLE_DISCUSSION_EMAIL_DIGEST': False,
 
-    """
-    .. toggle_name: ENABLE_UNICODE_USERNAME
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: False
-    .. toggle_description: Set this to True to allow unicode characters in username.
-      Enabling this will also automatically enable SOCIAL_AUTH_CLEAN_USERNAMES. When
-      this is enabled, usernames will have to match the regular expression defined by
-      USERNAME_REGEX_PARTIAL.
-    .. toggle_category: admin
-    .. toggle_use_cases: open_edx
-    .. toggle_creation_date: 2017-06-27
-    .. toggle_expiration_date: None
-    .. toggle_warnings: None
-    .. toggle_tickets: https://github.com/edx/edx-platform/pull/14729
-    .. toggle_status: supported
-    """
+    # toggle_name: ENABLE_UNICODE_USERNAME
+    # toggle_implementation: DjangoSetting
+    # toggle_default: False
+    # toggle_description: Set this to True to allow unicode characters in username. Enabling this will also automatically enable SOCIAL_AUTH_CLEAN_USERNAMES. When this is enabled, usernames will have to match the regular expression defined by USERNAME_REGEX_PARTIAL.
+    # toggle_category: admin
+    # toggle_use_cases: open_edx
+    # toggle_creation_date: 2017-06-27
+    # toggle_expiration_date: None
+    # toggle_warnings: None
+    # toggle_tickets: https://github.com/edx/edx-platform/pull/14729
+    # toggle_status: supported
     'ENABLE_UNICODE_USERNAME': False,
 
     'ENABLE_DJANGO_ADMIN_SITE': True,  # set true to enable django's admin site, even on prod (e.g. for course ops)
@@ -158,20 +146,17 @@ FEATURES = {
 
     'DISABLE_LOGIN_BUTTON': False,  # used in systems where login is automatic, eg MIT SSL
 
-    """
-    .. toggle_name: ENABLE_OAUTH2_PROVIDER
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: False
-    .. toggle_description: Enable this feature to allow this Open edX platform to be an
-      OAuth2 authentication provider. This is necessary to enable some other features,
-      such as the REST API for the mobile application.
-    .. toggle_category: admin
-    .. toggle_use_cases: monitored_rollout
-    .. toggle_creation_date: 2014-09-09
-    .. toggle_expiration_date: None
-    .. toggle_status: supported
-    .. toggle_warnings: None
-    """
+    # .. toggle_name: ENABLE_OAUTH2_PROVIDER
+    # .. toggle_implementation: DjangoSetting
+    # .. toggle_default: False
+    # .. toggle_description: Enable this feature to allow this Open edX platform to be an OAuth2 authentication
+    #   provider. This is necessary to enable some other features, such as the REST API for the mobile application.
+    # .. toggle_category: admin
+    # .. toggle_use_cases: monitored_rollout
+    # .. toggle_creation_date: 2014-09-09
+    # .. toggle_expiration_date: None
+    # .. toggle_status: supported
+    # .. toggle_warnings: None
     'ENABLE_OAUTH2_PROVIDER': False,
 
     # Allows to enable an API endpoint to serve XBlock view, used for example by external applications.
@@ -239,51 +224,39 @@ FEATURES = {
     # for acceptance and load testing
     'AUTOMATIC_AUTH_FOR_TESTING': False,
 
-    """
-    .. toggle_name: RESTRICT_AUTOMATIC_AUTH
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: True
-    .. toggle_description: Prevent auto auth from creating superusers or modifying
-    existing users. Auto auth is a mechanism where superusers can simply modify
-    attributes of other users by accessing the "/auto_auth url" with the right
-    querystring parameters.
-    .. toggle_category: admin
-    .. toggle_use_cases: open_edx
-    .. toggle_creation_date: 2018-05-07
-    .. toggle_expiration_date: None
-    .. toggle_tickets: https://openedx.atlassian.net/browse/TE-2545
-    .. toggle_status: supported
-    """
+    # .. toggle_name: RESTRICT_AUTOMATIC_AUTH
+    # .. toggle_implementation: DjangoSetting
+    # .. toggle_default: True
+    # .. toggle_description: Prevent auto auth from creating superusers or modifying existing users. Auto auth is a mechanism where superusers can simply modify attributes of other users by accessing the "/auto_auth url" with the right querystring parameters.
+    # .. toggle_category: admin
+    # .. toggle_use_cases: open_edx
+    # .. toggle_creation_date: 2018-05-07
+    # .. toggle_expiration_date: None
+    # .. toggle_tickets: https://openedx.atlassian.net/browse/TE-2545
+    # .. toggle_status: supported
     'RESTRICT_AUTOMATIC_AUTH': True,
 
-    """
-    .. toggle_name: ENABLE_LOGIN_MICROFRONTEND
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: False
-    .. toggle_description: Enable the login micro frontend.
-    .. toggle_category: admin
-    .. toggle_use_cases: open_edx
-    .. toggle_creation_date: 2018-05-07
-    .. toggle_expiration_date: None
-    .. toggle_warnings: The login MFE domain name should be listed in
-      LOGIN_REDIRECT_WHITELIST.
-    .. toggle_status: supported
-    """
+    # toggle_name: ENABLE_LOGIN_MICROFRONTEND
+    # toggle_implementation: DjangoSetting
+    # toggle_default: False
+    # toggle_description: Enable the login micro frontend.
+    # toggle_category: admin
+    # toggle_use_cases: open_edx
+    # toggle_creation_date: 2018-05-07
+    # toggle_expiration_date: None
+    # toggle_warnings: The login MFE domain name should be listed in LOGIN_REDIRECT_WHITELIST.
+    # toggle_status: supported
     'ENABLE_LOGIN_MICROFRONTEND': False,
 
-    """
-    .. toggle_name: SKIP_EMAIL_VALIDATION
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: False
-    .. toggle_description: Turn this on to skip sending emails for user validation.
-      Beware, as this leaves the door open to potential spam abuse.
-    .. toggle_category: admin
-    .. toggle_use_cases: open_edx
-    .. toggle_expiration_date: None
-    .. toggle_warnings: The login MFE domain name should be listed in
-      LOGIN_REDIRECT_WHITELIST.
-    .. toggle_status: supported
-    """
+    # toggle_name: SKIP_EMAIL_VALIDATION
+    # toggle_implementation: DjangoSetting
+    # toggle_default: False
+    # toggle_description: Turn this on to skip sending emails for user validation. Beware, as this leaves the door open to potential spam abuse.
+    # toggle_category: admin
+    # toggle_use_cases: open_edx
+    # toggle_expiration_date: None
+    # toggle_warnings: The login MFE domain name should be listed in LOGIN_REDIRECT_WHITELIST.
+    # toggle_status: supported
     'SKIP_EMAIL_VALIDATION': False,
 
     # Toggle the availability of the shopping cart page
@@ -326,23 +299,16 @@ FEATURES = {
     # defaults, so that we maintain current behavior
     'ALLOW_WIKI_ROOT_ACCESS': True,
 
-    """
-    .. toggle_name: ENABLE_THIRD_PARTY_AUTH
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: False
-    .. toggle_description: Turn on third-party auth. Disabled for now because full
-      implementations are not yet available. Remember to run
-      migrations if you enable this; we don't create tables by default. This feature
-      can be enabled on a per-site basis. When enabling this feature, remember to
-      define the allowed authentication backends with the AUTHENTICATION_BACKENDS
-      setting.
-    .. toggle_category: admin
-    .. toggle_use_cases: open_edx
-    .. toggle_creation_date: 2014-09-15
-    .. toggle_expiration_date: None
-    .. toggle_status: supported
-    .. toggle_warnings: None
-    """
+    # toggle_name: ENABLE_THIRD_PARTY_AUTH
+    # toggle_implementation: DjangoSetting
+    # toggle_default: False
+    # toggle_description: Turn on third-party auth. Disabled for now because full implementations are not yet available. Remember to run migrations if you enable this; we don't create tables by default. This feature can be enabled on a per-site basis. When enabling this feature, remember to define the allowed authentication backends with the AUTHENTICATION_BACKENDS setting.
+    # toggle_category: admin
+    # toggle_use_cases: open_edx
+    # toggle_creation_date: 2014-09-15
+    # toggle_expiration_date: None
+    # toggle_status: supported
+    # toggle_warnings: None
     'ENABLE_THIRD_PARTY_AUTH': False,
 
     # Toggle to enable alternate urls for marketing links
@@ -365,20 +331,17 @@ FEATURES = {
     # ENABLE_OAUTH2_PROVIDER to True
     'ENABLE_MOBILE_REST_API': False,
 
-    """
-    .. toggle_name: ENABLE_COMBINED_LOGIN_REGISTRATION_FOOTER
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: False
-    .. toggle_description: Display the standard footer in the login page. This feature
-      can be overridden by a site-specific configuration.
-    .. toggle_category: admin
-    .. toggle_use_cases: open_edx
-    .. toggle_creation_date: 2016-06-24
-    .. toggle_expiration_date: None
-    .. toggle_tickets: https://openedx.atlassian.net/browse/OSPR-1320
-    .. toggle_status: supported
-    .. toggle_warnings: None
-    """
+    # .. toggle_name: ENABLE_COMBINED_LOGIN_REGISTRATION_FOOTER
+    # .. toggle_implementation: DjangoSetting
+    # .. toggle_default: False
+    # .. toggle_description: Display the standard footer in the login page. This feature can be overridden by a site-specific configuration.
+    # .. toggle_category: admin
+    # .. toggle_use_cases: open_edx
+    # .. toggle_creation_date: 2016-06-24
+    # .. toggle_expiration_date: None
+    # .. toggle_tickets: https://openedx.atlassian.net/browse/OSPR-1320
+    # .. toggle_status: supported
+    # .. toggle_warnings: None
     'ENABLE_COMBINED_LOGIN_REGISTRATION_FOOTER': False,
 
     # Enable organizational email opt-in
@@ -478,20 +441,17 @@ FEATURES = {
     # Set this to False to facilitate cleaning up invalid xml from your modulestore.
     'ENABLE_XBLOCK_XML_VALIDATION': True,
 
-    """
-    .. toggle_name: ALLOW_PUBLIC_ACCOUNT_CREATION
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: True
-    .. toggle_description: Allow public account creation. If this is disabled, users
-      will no longer have access to the signup page.
-    .. toggle_category: admin
-    .. toggle_use_cases: open_edx
-    .. toggle_creation_date: 2017-04-12
-    .. toggle_expiration_date: None
-    .. toggle_tickets: https://openedx.atlassian.net/browse/YONK-513
-    .. toggle_status: supported
-    .. toggle_warnings: None
-    """
+    # .. toggle_name: ALLOW_PUBLIC_ACCOUNT_CREATION
+    # .. toggle_implementation: DjangoSetting
+    # .. toggle_default: True
+    # .. toggle_description: Allow public account creation. If this is disabled, users will no longer have access to the signup page.
+    # .. toggle_category: admin
+    # .. toggle_use_cases: open_edx
+    # .. toggle_creation_date: 2017-04-12
+    # .. toggle_expiration_date: None
+    # .. toggle_tickets: https://openedx.atlassian.net/browse/YONK-513
+    # .. toggle_status: supported
+    # .. toggle_warnings: None
     'ALLOW_PUBLIC_ACCOUNT_CREATION': True,
 
     # Enable footer banner for cookie consent.
@@ -520,23 +480,17 @@ FEATURES = {
     # Whether HTML XBlocks/XModules return HTML content with the Course Blocks API student_view_data
     'ENABLE_HTML_XBLOCK_STUDENT_VIEW_DATA': False,
 
-    """
-    .. toggle_name: ENABLE_CHANGE_USER_PASSWORD_ADMIN
-    .. toggle_implementation: DjangoSetting
-    .. toggle_default: False
-    .. toggle_description: Whether to send an email for failed password reset attempts
-      or not. This happens when a user asks for a password reset but they don't have an
-      account associated to their email. This is useful for notifying users that they
-      don't have an account associated with email addresses they believe they've
-      registered with. This setting can be overridden by a site-specific configuration.
-    .. toggle_category: admin
-    .. toggle_use_cases: open_edx
-    .. toggle_creation_date: 2017-07-20
-    .. toggle_expiration_date: None
-    .. toggle_tickets: https://openedx.atlassian.net/browse/OSPR-1832
-    .. toggle_status: supported
-    .. toggle_warnings: None
-    """
+    # .. toggle_name: ENABLE_CHANGE_USER_PASSWORD_ADMIN
+    # .. toggle_implementation: DjangoSetting
+    # .. toggle_default: False
+    # .. toggle_description: Whether to send an email for failed password reset attempts or not. This happens when a user asks for a password reset but they don't have an account associated to their email. This is useful for notifying users that they don't have an account associated with email addresses they believe they've registered with. This setting can be overridden by a site-specific configuration.
+    # .. toggle_category: admin
+    # .. toggle_use_cases: open_edx
+    # .. toggle_creation_date: 2017-07-20
+    # .. toggle_expiration_date: None
+    # .. toggle_tickets: https://openedx.atlassian.net/browse/OSPR-1832
+    # .. toggle_status: supported
+    # .. toggle_warnings: None
     'ENABLE_PASSWORD_RESET_FAILURE_EMAIL': False,
 
     # Sets the default browser support. For more information go to http://browser-update.org/customize.html
-- 
GitLab