Merge pull request #24794 from regisb/regisb/settings-docs

[BD-21] Document settings with annotations

Makefile

@@ -21,7 +21,7 @@ clean: ## archive and delete most git-ignored files
 
 SWAGGER = docs/swagger.yaml
 
-docs: api-docs guides feature-toggles-docs ## build all the developer documentation for this repository
+docs: api-docs guides technical-docs ## build all the developer documentation for this repository
 
 swagger: ## generate the swagger.yaml file
 	DJANGO_SETTINGS_MODULE=docs.docs_settings python manage.py lms generate_swagger --generator-class=edx_api_doc_tools.ApiSchemaGenerator -o $(SWAGGER)
@@ -33,8 +33,8 @@ api-docs-sphinx: swagger	## generate the sphinx source files for api-docs
 api-docs: api-docs-sphinx	## build the REST api docs
 	cd docs/api; make html
 
-feature-toggles-docs:
-	$(MAKE) -C docs/featuretoggles html
+technical-docs:  ## build the technical docs
+	$(MAKE) -C docs/technical html
 
 guides:	## build the developer guide docs
 	cd docs/guides; make clean html

cms/envs/common.py

@@ -161,6 +161,12 @@ PLATFORM_TWITTER_ACCOUNT = "@YourPlatformTwitterAccount"
 # Dummy secret key for dev/test
 SECRET_KEY = 'dev key'
 FAVICON_PATH = 'images/favicon.ico'
+
+
+# .. setting_name: STUDIO_NAME
+# .. setting_default: Your Platform Studio
+# .. setting_description: The name that will appear on the landing page of Studio, as well as in various emails and
+#   templates.
 STUDIO_NAME = _("Your Platform Studio")
 STUDIO_SHORT_NAME = _("Studio")
 FEATURES = {

docs/technical/conf.py

@@ -1,5 +1,5 @@
 """
-Configuration file for the generation of feature toggle documentation.
+Configuration file for the generation of technical documentation.
 """
 import os
 
@@ -8,27 +8,34 @@ import git
 
 # -- Project information -----------------------------------------------------
 
-project = "Open edX feature toggles"
+project = "edx-platform technical reference"
 copyright = edx_theme.COPYRIGHT  # pylint: disable=redefined-builtin
 author = edx_theme.AUTHOR
 release = ""
 
 # -- General configuration ---------------------------------------------------
 
-extensions = ["code_annotations.config_and_tools.sphinx.extensions.featuretoggles"]
+extensions = ["code_annotations.contrib.sphinx.extensions.featuretoggles", "code_annotations.contrib.sphinx.extensions.settings"]
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-featuretoggles_source_path = os.path.abspath(
+edxplatform_repo_url = "https://github.com/edx/edx-platform"
+edxplatform_source_path = os.path.abspath(
     os.path.join(os.path.dirname(__file__), "..", "..")
 )
-featuretoggles_repo_url = "https://github.com/edx/edx-platform"
 try:
     edx_platform_version = git.Repo(search_parent_directories=True).head.object.hexsha
 except git.InvalidGitRepositoryError:
     edx_platform_version = "master"
+
+featuretoggles_source_path = edxplatform_source_path
+featuretoggles_repo_url = edxplatform_repo_url
 featuretoggles_repo_version = edx_platform_version
 
+settings_source_path = edxplatform_source_path
+settings_repo_url = edxplatform_repo_url
+settings_repo_version = edx_platform_version
+
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = "edx_theme"

docs/technical/featuretoggles.rst

@@ -1,5 +1,7 @@
-Open edX Feature Toggles
-========================
+.. _featuretoggles:
+
+Feature Toggles
+===============
 
 This is the list of all Open edX feature toggles used in edx-platform. These feature toggles can be used to enable or disable features manually on every platform.
 

docs/technical/index.rst

@@ -0,0 +1,9 @@
+====================================
+``edx-platform`` technical reference
+====================================
+
+This is the technical documentation reference for edx-platform.
+
+.. toctree::
+    settings
+    featuretoggles

docs/technical/settings.rst

@@ -0,0 +1,19 @@
+Settings
+========
+
+This is the list of (non-toggle) Django settings defined in the ``common.py`` modules of edx-platform.
+
+.. note::
+    Toggle settings, which enable or disable a specific feature, are documented in the :ref:`feature toggles <featuretoggles>` section.
+
+LMS settings
+------------
+
+.. settings::
+    :folder_path: lms/envs/common.py
+
+CMS settings
+------------
+
+.. settings::
+    :folder_path: cms/envs/common.py

lms/envs/common.py

@@ -55,7 +55,10 @@ from openedx.core.release import doc_version
 from lms.djangoapps.lms_xblock.mixin import LmsBlockMixin
 
 ################################### FEATURES ###################################
-# The display name of the platform to be used in templates/emails/etc.
+# .. setting_name: PLATFORM_NAME
+# .. setting_default: Your Platform Name Here
+# .. setting_description: The display name of the platform to be used in
+#     templates/emails/etc.
 PLATFORM_NAME = _('Your Platform Name Here')
 PLATFORM_DESCRIPTION = _('Your Platform Description Here')
 CC_MERCHANT_NAME = PLATFORM_NAME

openedx/core/djangoapps/content_libraries/tests/base.py

@@ -4,12 +4,12 @@ Tests for Blockstore-based Content Libraries
 """
 from contextlib import contextmanager
 from io import BytesIO
-from mock import patch
 from urllib.parse import urlencode
 import unittest
 
 from django.conf import settings
 from django.test.utils import override_settings
+from mock import patch
 from organizations.models import Organization
 from rest_framework.test import APITestCase, APIClient
 from search.search_engine_base import SearchEngine