From 7a0f2682acbdff22f4026bd3dd3241a94712e292 Mon Sep 17 00:00:00 2001
From: Feanil Patel <feanil@axim.org>
Date: Thu, 29 Jun 2023 16:10:42 -0400
Subject: [PATCH] docs: Add feature toggle and settings to the guide.

With this move we don't need the existing separate `edx-platform
Technical` sphinx project.  In the future we can remove it and just
redirect to the content in this project but I won't be doing that as a
part of this change because that involves adding redirects over there to
the new content and I'm not yet done organizing the destination.

The docs in the `guide` project might move around as we make the project
follow diataxis more closely.
---
 docs/guides/conf.py            | 22 ++++++++++++++++++++++
 docs/guides/featuretoggles.rst |  8 ++++++++
 docs/guides/index.rst          |  4 +++-
 docs/guides/settings.rst       | 19 +++++++++++++++++++
 4 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 docs/guides/featuretoggles.rst
 create mode 100644 docs/guides/settings.rst

diff --git a/docs/guides/conf.py b/docs/guides/conf.py
index f0491d5598..221383b53b 100644
--- a/docs/guides/conf.py
+++ b/docs/guides/conf.py
@@ -12,6 +12,8 @@ from datetime import datetime
 from subprocess import check_call
 
 import django
+import git
+
 from path import Path
 
 root = Path('../..').abspath()
@@ -60,8 +62,28 @@ extensions = [
     '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
new file mode 100644
index 0000000000..6c697e5014
--- /dev/null
+++ 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
index 371fce5586..49ce6eb8cb 100644
--- 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
new file mode 100644
index 0000000000..79b366e990
--- /dev/null
+++ 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