Merge pull request #24344 from regisb/regisb/toggles-docs

[BD-21] Generate feature toggle documentation

Makefile

@@ -21,7 +21,7 @@ clean: ## archive and delete most git-ignored files
 
 SWAGGER = docs/swagger.yaml
 
-docs: api-docs guides ## build all the developer documentation for this repository
+docs: api-docs guides feature-toggles-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,6 +33,9 @@ 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
+
 guides:	## build the developer guide docs
 	cd docs/guides; make clean html
 
@@ -75,6 +78,7 @@ shell: ## launch a bash shell in a Docker container with all edx-platform depend
 REQ_FILES = \
 	requirements/edx/pip-tools \
 	requirements/edx/coverage \
+	requirements/edx/doc \
 	requirements/edx/paver \
 	requirements/edx-sandbox/shared \
 	requirements/edx-sandbox/py35 \

docs/featuretoggles/.gitignore

@@ -0,0 +1 @@
+_build

docs/featuretoggles/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/featuretoggles/conf.py

@@ -0,0 +1,36 @@
+"""
+Configuration file for the generation of feature toggle documentation.
+"""
+import os
+
+import edx_theme
+import git
+
+# -- Project information -----------------------------------------------------
+
+project = "Open edX feature toggles"
+copyright = edx_theme.COPYRIGHT  # pylint: disable=redefined-builtin
+author = edx_theme.AUTHOR
+release = ""
+
+# -- General configuration ---------------------------------------------------
+
+extensions = ["code_annotations.config_and_tools.sphinx.extensions.featuretoggles"]
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+featuretoggles_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_repo_version = edx_platform_version
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "edx_theme"
+html_theme_path = [edx_theme.get_html_theme_path()]
+html_static_path = ["_static"]

docs/featuretoggles/index.rst

@@ -0,0 +1,6 @@
+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::

requirements/edx/doc.in

@@ -0,0 +1,7 @@
+# Requirements for documentation validation
+-c ../constraints.txt
+
+code-annotations          # provides annotations for certain documentation
+edx_sphinx_theme          # edX theme for Sphinx output
+gitpython                 # fetch git repo information
+Sphinx                    # Documentation builder

requirements/edx/doc.txt

@@ -0,0 +1,46 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+#    make upgrade
+#
+alabaster==0.7.12         # via sphinx
+babel==2.8.0              # via sphinx
+certifi==2020.6.20        # via requests
+chardet==3.0.4            # via requests
+click==7.1.2              # via code-annotations
+code-annotations==0.5.0   # via -r requirements/edx/doc.in
+django==2.2.15            # via -c requirements/edx/../constraints.txt, code-annotations
+docutils==0.16            # via sphinx
+edx-sphinx-theme==1.5.0   # via -r requirements/edx/doc.in
+gitdb==4.0.5              # via gitpython
+gitpython==3.1.7          # via -r requirements/edx/doc.in
+idna==2.10                # via requests
+imagesize==1.2.0          # via sphinx
+jinja2==2.11.2            # via code-annotations, sphinx
+markupsafe==1.1.1         # via jinja2
+packaging==20.4           # via sphinx
+pbr==5.4.5                # via stevedore
+pygments==2.6.1           # via sphinx
+pyparsing==2.4.7          # via packaging
+python-slugify==4.0.1     # via code-annotations
+pytz==2020.1              # via babel, django
+pyyaml==5.3.1             # via code-annotations
+requests==2.24.0          # via sphinx
+six==1.15.0               # via edx-sphinx-theme, packaging, stevedore
+smmap==3.0.4              # via gitdb
+snowballstemmer==2.0.0    # via sphinx
+sphinx==3.1.2             # via -r requirements/edx/doc.in, edx-sphinx-theme
+sphinxcontrib-applehelp==1.0.2  # via sphinx
+sphinxcontrib-devhelp==1.0.2  # via sphinx
+sphinxcontrib-htmlhelp==1.0.3  # via sphinx
+sphinxcontrib-jsmath==1.0.1  # via sphinx
+sphinxcontrib-qthelp==1.0.3  # via sphinx
+sphinxcontrib-serializinghtml==1.1.4  # via sphinx
+sqlparse==0.3.1           # via django
+stevedore==1.32.0         # via -c requirements/edx/../constraints.txt, code-annotations
+text-unidecode==1.3       # via python-slugify
+urllib3==1.25.10          # via requests
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools