From e555d8a571c5bc844675d2ed633706e078656bcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9gis=20Behmo?= Date: Mon, 21 Sep 2020 10:56:39 +0200 Subject: [PATCH 1/2] [BD-21] Document settings with annotations We introduce the documentation of django settings via code annotations. This will allow us to produce a human-readable documentatio of all Open edX settings. --- cms/envs/common.py | 6 ++++++ docs/featuretoggles/conf.py | 13 ++++++++++--- docs/featuretoggles/index.rst | 19 +++++++++++++++++++ lms/envs/common.py | 5 ++++- .../content_libraries/tests/base.py | 2 +- 5 files changed, 40 insertions(+), 5 deletions(-) diff --git a/cms/envs/common.py b/cms/envs/common.py index a6f8d1cb19..0f9e213c0c 100644 --- a/cms/envs/common.py +++ b/cms/envs/common.py @@ -160,6 +160,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 = { diff --git a/docs/featuretoggles/conf.py b/docs/featuretoggles/conf.py index 6f81e8cb59..63e23d526e 100644 --- a/docs/featuretoggles/conf.py +++ b/docs/featuretoggles/conf.py @@ -15,20 +15,27 @@ 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" diff --git a/docs/featuretoggles/index.rst b/docs/featuretoggles/index.rst index 3529c2a420..b246c4e5c4 100644 --- a/docs/featuretoggles/index.rst +++ b/docs/featuretoggles/index.rst @@ -1,3 +1,22 @@ +Open edX Django settings +======================== + +This is the list of Django settings defined in the ``common.py`` modules of edx-platform. + +LMS settings +------------ + +.. TODO move this to a dedicated page +.. settings:: + :folder_path: lms/envs/common.py + +CMS settings +------------ + +.. settings:: + :folder_path: cms/envs/common.py + + Open edX Feature Toggles ======================== diff --git a/lms/envs/common.py b/lms/envs/common.py index 3c30263ff8..137518141a 100644 --- a/lms/envs/common.py +++ b/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 diff --git a/openedx/core/djangoapps/content_libraries/tests/base.py b/openedx/core/djangoapps/content_libraries/tests/base.py index e15cf7b5f4..28fe748559 100644 --- a/openedx/core/djangoapps/content_libraries/tests/base.py +++ b/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 From a41f2a5ca86c0c81d8192f2b05489b1c7c1e4ca5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9gis=20Behmo?= Date: Mon, 21 Sep 2020 11:05:37 +0200 Subject: [PATCH 2/2] Rename "featuretoggles" docs target to "technical" We also split the feature toggle and settings docs in different pages. --- Makefile | 6 ++--- docs/featuretoggles/index.rst | 25 ------------------- docs/{featuretoggles => technical}/.gitignore | 0 docs/{featuretoggles => technical}/Makefile | 0 docs/{featuretoggles => technical}/conf.py | 4 +-- docs/technical/featuretoggles.rst | 8 ++++++ docs/technical/index.rst | 9 +++++++ docs/technical/settings.rst | 19 ++++++++++++++ 8 files changed, 41 insertions(+), 30 deletions(-) delete mode 100644 docs/featuretoggles/index.rst rename docs/{featuretoggles => technical}/.gitignore (100%) rename docs/{featuretoggles => technical}/Makefile (100%) rename docs/{featuretoggles => technical}/conf.py (92%) create mode 100644 docs/technical/featuretoggles.rst create mode 100644 docs/technical/index.rst create mode 100644 docs/technical/settings.rst diff --git a/Makefile b/Makefile index 47e19bfe7b..537162e48a 100644 --- a/Makefile +++ b/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 diff --git a/docs/featuretoggles/index.rst b/docs/featuretoggles/index.rst deleted file mode 100644 index b246c4e5c4..0000000000 --- a/docs/featuretoggles/index.rst +++ /dev/null @@ -1,25 +0,0 @@ -Open edX Django settings -======================== - -This is the list of Django settings defined in the ``common.py`` modules of edx-platform. - -LMS settings ------------- - -.. TODO move this to a dedicated page -.. settings:: - :folder_path: lms/envs/common.py - -CMS settings ------------- - -.. settings:: - :folder_path: cms/envs/common.py - - -Open edX 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. - -.. featuretoggles:: diff --git a/docs/featuretoggles/.gitignore b/docs/technical/.gitignore similarity index 100% rename from docs/featuretoggles/.gitignore rename to docs/technical/.gitignore diff --git a/docs/featuretoggles/Makefile b/docs/technical/Makefile similarity index 100% rename from docs/featuretoggles/Makefile rename to docs/technical/Makefile diff --git a/docs/featuretoggles/conf.py b/docs/technical/conf.py similarity index 92% rename from docs/featuretoggles/conf.py rename to docs/technical/conf.py index 63e23d526e..cafdfc9e75 100644 --- a/docs/featuretoggles/conf.py +++ b/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,7 +8,7 @@ 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 = "" diff --git a/docs/technical/featuretoggles.rst b/docs/technical/featuretoggles.rst new file mode 100644 index 0000000000..6c697e5014 --- /dev/null +++ b/docs/technical/featuretoggles.rst @@ -0,0 +1,8 @@ +.. _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. + +.. featuretoggles:: diff --git a/docs/technical/index.rst b/docs/technical/index.rst new file mode 100644 index 0000000000..db8843c4ce --- /dev/null +++ b/docs/technical/index.rst @@ -0,0 +1,9 @@ +==================================== +``edx-platform`` technical reference +==================================== + +This is the technical documentation reference for edx-platform. + +.. toctree:: + settings + featuretoggles diff --git a/docs/technical/settings.rst b/docs/technical/settings.rst new file mode 100644 index 0000000000..79b366e990 --- /dev/null +++ b/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 ` section. + +LMS settings +------------ + +.. settings:: + :folder_path: lms/envs/common.py + +CMS settings +------------ + +.. settings:: + :folder_path: cms/envs/common.py