Merge pull request openedx#32612 from openedx/feanil/merge_tech_docs

docs: Add feature toggle and settings to the guide.
eduNEXT · Jul 10, 2023 · f45af06 · f45af06
2 parents 051ecb4 + 7a0f268
commit f45af06
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 1 deletion.
diff --git a/docs/guides/conf.py b/docs/guides/conf.py
@@ -12,6 +12,8 @@
 from subprocess import check_call
 
 import django
+import git
+
 from path import Path
 
 root = Path('../..').abspath()
@@ -60,8 +62,28 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
     'sphinxcontrib.openapi',
+    'code_annotations.contrib.sphinx.extensions.featuretoggles',
+    'code_annotations.contrib.sphinx.extensions.settings',
 ]
 
+# code_annotations.(featuretoggles|settings) related settings.
+edxplatform_repo_url = "https://github.com/openedx/edx-platform"
+edxplatform_source_path = os.path.abspath(
+    os.path.join(os.path.dirname(__file__), "..", "..")
+)
+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
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

diff --git a/docs/guides/featuretoggles.rst b/docs/guides/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/guides/index.rst b/docs/guides/index.rst
@@ -22,12 +22,14 @@ locations.
 .. _Open edX ReadTheDocs: http://docs.edx.org/
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
     lms_apis
     guides
     docstrings/docstrings
     celery
+    settings
+    featuretoggles
 
 
 Change History

diff --git a/docs/guides/settings.rst b/docs/guides/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