From 2c8105f7ae966f1878a4a30fe85b8ba76fe94994 Mon Sep 17 00:00:00 2001 From: Robert Raposa Date: Fri, 10 Jul 2020 15:51:19 -0400 Subject: [PATCH] [BD-21] Generate feature toggle documentation We introduce a new documentation target, where we use the featuretoggles Sphinx extension from code-annotations to generate human-readable documentation of feature toggles in edx-platform. The annotation report is generated on-the-fly based on the standard feature toggle configuration file in code-annotations. In addition, we add new doc.in & doc.txt requirement files that will be pip-installed by readthedocs to generate the documentation targets. --- Makefile | 6 ++++- docs/featuretoggles/.gitignore | 1 + docs/featuretoggles/Makefile | 20 +++++++++++++++ docs/featuretoggles/conf.py | 36 ++++++++++++++++++++++++++ docs/featuretoggles/index.rst | 6 +++++ requirements/edx/doc.in | 7 ++++++ requirements/edx/doc.txt | 46 ++++++++++++++++++++++++++++++++++ 7 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 docs/featuretoggles/.gitignore create mode 100644 docs/featuretoggles/Makefile create mode 100644 docs/featuretoggles/conf.py create mode 100644 docs/featuretoggles/index.rst create mode 100644 requirements/edx/doc.in create mode 100644 requirements/edx/doc.txt diff --git a/Makefile b/Makefile index b711b6c59e..28226a4ff7 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 ## 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 \ diff --git a/docs/featuretoggles/.gitignore b/docs/featuretoggles/.gitignore new file mode 100644 index 0000000000..e35d8850c9 --- /dev/null +++ b/docs/featuretoggles/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/featuretoggles/Makefile b/docs/featuretoggles/Makefile new file mode 100644 index 0000000000..c7271eadef --- /dev/null +++ b/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) diff --git a/docs/featuretoggles/conf.py b/docs/featuretoggles/conf.py new file mode 100644 index 0000000000..6f81e8cb59 --- /dev/null +++ b/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"] diff --git a/docs/featuretoggles/index.rst b/docs/featuretoggles/index.rst new file mode 100644 index 0000000000..3529c2a420 --- /dev/null +++ b/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:: diff --git a/requirements/edx/doc.in b/requirements/edx/doc.in new file mode 100644 index 0000000000..1f0715f0bf --- /dev/null +++ b/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 diff --git a/requirements/edx/doc.txt b/requirements/edx/doc.txt new file mode 100644 index 0000000000..a546896d1d --- /dev/null +++ b/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