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/cms/envs/common.py b/cms/envs/common.py index c72989703b..21f6d0ddad 100644 --- a/cms/envs/common.py +++ b/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 = { 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 60% rename from docs/featuretoggles/conf.py rename to docs/technical/conf.py index 6f81e8cb59..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,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" diff --git a/docs/featuretoggles/index.rst b/docs/technical/featuretoggles.rst similarity index 77% rename from docs/featuretoggles/index.rst rename to docs/technical/featuretoggles.rst index 3529c2a420..6c697e5014 100644 --- a/docs/featuretoggles/index.rst +++ b/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. 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 diff --git a/lms/envs/common.py b/lms/envs/common.py index 22b12ca0b5..f07f54855a 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 a5f05d3317..6788c42349 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