From 1e27084e356b45925a09e7406e594f3e2280ec3e Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Tue, 18 Jul 2023 14:29:28 -0400 Subject: [PATCH 1/5] feat!: Drop the separate technical docs. BREAKING CHANGE: The technical docs will not be published independent of the rest of the edx-platform docs. --- docs/technical/.gitignore | 1 - docs/technical/Makefile | 20 -------- docs/technical/conf.py | 85 ------------------------------- docs/technical/featuretoggles.rst | 8 --- docs/technical/index.rst | 9 ---- docs/technical/settings.rst | 19 ------- 6 files changed, 142 deletions(-) delete mode 100644 docs/technical/.gitignore delete mode 100644 docs/technical/Makefile delete mode 100644 docs/technical/conf.py delete mode 100644 docs/technical/featuretoggles.rst delete mode 100644 docs/technical/index.rst delete mode 100644 docs/technical/settings.rst diff --git a/docs/technical/.gitignore b/docs/technical/.gitignore deleted file mode 100644 index e35d8850c9..0000000000 --- a/docs/technical/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_build diff --git a/docs/technical/Makefile b/docs/technical/Makefile deleted file mode 100644 index c7271eadef..0000000000 --- a/docs/technical/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# 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/technical/conf.py b/docs/technical/conf.py deleted file mode 100644 index 3b36915217..0000000000 --- a/docs/technical/conf.py +++ /dev/null @@ -1,85 +0,0 @@ -""" -Configuration file for the generation of technical documentation. -""" -import os -from datetime import datetime - -import git - -# -- Project information ----------------------------------------------------- - -project = "edx-platform Technical Reference" -copyright = f"{datetime.now().year}, Axim Collaborative, Inc" # pylint: disable=redefined-builtin -author = "Axim Collaborative, Inc" -release = "" - -# -- General configuration --------------------------------------------------- - -extensions = [ - "code_annotations.contrib.sphinx.extensions.featuretoggles", - "code_annotations.contrib.sphinx.extensions.settings", - "sphinx_reredirects", -] - -redirects = { - "*": "https://docs.openedx.org/projects/edx-platform/en/latest/$source.html", -} - -templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -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 - -# -- Options for HTML output ------------------------------------------------- - -html_theme = "sphinx_book_theme" -html_static_path = ["_static"] -html_favicon = "https://logos.openedx.org/open-edx-favicon.ico" -html_logo = "https://logos.openedx.org/open-edx-logo-color.png" - -html_theme_options = { - "repository_url": "https://github.com/openedx/edx-platform", - "repository_branch": "master", - "path_to_docs": "docs/technical", - "home_page_in_toc": True, - "use_repository_button": True, - "use_issues_button": True, - "use_edit_page_button": True, - # Please don't change unless you know what you're doing. - "extra_footer": """ - - Creative Commons License - -
- These works by - Axim Collaborative, Inc - are licensed under a - Creative Commons Attribution-ShareAlike 4.0 International License. - """, -} diff --git a/docs/technical/featuretoggles.rst b/docs/technical/featuretoggles.rst deleted file mode 100644 index 6c697e5014..0000000000 --- a/docs/technical/featuretoggles.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _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/technical/index.rst b/docs/technical/index.rst deleted file mode 100644 index db8843c4ce..0000000000 --- a/docs/technical/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -==================================== -``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 deleted file mode 100644 index 79b366e990..0000000000 --- a/docs/technical/settings.rst +++ /dev/null @@ -1,19 +0,0 @@ -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 From 3e2d78b37bb9007bd1a81d5626ff817f45b8b403 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Tue, 18 Jul 2023 14:31:49 -0400 Subject: [PATCH 2/5] feat!: Move the docs out of the guides subdirectory. Now that the content in `guides` is all of the edx-platform docs, move them all into the top-level docs directory to reduce confusion. BREAKING CHANGE: Guides are now just docs. This will require updating the publishing settings so that RTD looks for the conf in a different location. --- docs/{guides => }/.gitignore | 0 docs/{guides => }/Makefile | 0 docs/{guides => }/concepts/extension_points.rst | 0 docs/{guides => }/concepts/frontend/bootstrap.rst | 0 docs/{guides => }/concepts/frontend/javascript.rst | 0 .../concepts/frontend/static_assets.rst | 0 docs/{guides => }/concepts/frontend/styling.rst | 0 docs/{guides => }/concepts/index.rst | 0 docs/{guides => }/concepts/testing/test_pyramid.png | Bin docs/{guides => }/concepts/testing/testing.rst | 0 docs/{guides => }/conf.py | 0 docs/{guides => }/extensions/tinymce_plugins.rst | 0 docs/guides/__init__.py | 0 docs/{guides => }/hooks/events.rst | 0 docs/{guides => }/hooks/filters.rst | 0 docs/{guides => }/hooks/index.rst | 0 docs/{guides => }/how-tos/celery.rst | 0 docs/{guides => }/how-tos/index.rst | 0 docs/{guides => }/index.rst | 0 docs/{guides => }/make.bat | 0 docs/{guides => }/redirects.txt | 0 .../references/docstrings/cms_index.rst | 0 .../references/docstrings/common_djangoapps.rst | 0 .../references/docstrings/common_index.rst | 0 docs/{guides => }/references/docstrings/index.rst | 0 .../references/docstrings/lms_index.rst | 0 docs/{guides => }/references/featuretoggles.rst | 0 docs/{guides => }/references/index.rst | 0 docs/{guides => }/references/lms_apis.rst | 0 docs/{guides => }/references/settings.rst | 0 docs/{guides => }/studio_oauth.rst | 0 docs/{guides => }/v1_sass_pipeline.webp | Bin 32 files changed, 0 insertions(+), 0 deletions(-) rename docs/{guides => }/.gitignore (100%) rename docs/{guides => }/Makefile (100%) rename docs/{guides => }/concepts/extension_points.rst (100%) rename docs/{guides => }/concepts/frontend/bootstrap.rst (100%) rename docs/{guides => }/concepts/frontend/javascript.rst (100%) rename docs/{guides => }/concepts/frontend/static_assets.rst (100%) rename docs/{guides => }/concepts/frontend/styling.rst (100%) rename docs/{guides => }/concepts/index.rst (100%) rename docs/{guides => }/concepts/testing/test_pyramid.png (100%) rename docs/{guides => }/concepts/testing/testing.rst (100%) rename docs/{guides => }/conf.py (100%) rename docs/{guides => }/extensions/tinymce_plugins.rst (100%) delete mode 100644 docs/guides/__init__.py rename docs/{guides => }/hooks/events.rst (100%) rename docs/{guides => }/hooks/filters.rst (100%) rename docs/{guides => }/hooks/index.rst (100%) rename docs/{guides => }/how-tos/celery.rst (100%) rename docs/{guides => }/how-tos/index.rst (100%) rename docs/{guides => }/index.rst (100%) rename docs/{guides => }/make.bat (100%) rename docs/{guides => }/redirects.txt (100%) rename docs/{guides => }/references/docstrings/cms_index.rst (100%) rename docs/{guides => }/references/docstrings/common_djangoapps.rst (100%) rename docs/{guides => }/references/docstrings/common_index.rst (100%) rename docs/{guides => }/references/docstrings/index.rst (100%) rename docs/{guides => }/references/docstrings/lms_index.rst (100%) rename docs/{guides => }/references/featuretoggles.rst (100%) rename docs/{guides => }/references/index.rst (100%) rename docs/{guides => }/references/lms_apis.rst (100%) rename docs/{guides => }/references/settings.rst (100%) rename docs/{guides => }/studio_oauth.rst (100%) rename docs/{guides => }/v1_sass_pipeline.webp (100%) diff --git a/docs/guides/.gitignore b/docs/.gitignore similarity index 100% rename from docs/guides/.gitignore rename to docs/.gitignore diff --git a/docs/guides/Makefile b/docs/Makefile similarity index 100% rename from docs/guides/Makefile rename to docs/Makefile diff --git a/docs/guides/concepts/extension_points.rst b/docs/concepts/extension_points.rst similarity index 100% rename from docs/guides/concepts/extension_points.rst rename to docs/concepts/extension_points.rst diff --git a/docs/guides/concepts/frontend/bootstrap.rst b/docs/concepts/frontend/bootstrap.rst similarity index 100% rename from docs/guides/concepts/frontend/bootstrap.rst rename to docs/concepts/frontend/bootstrap.rst diff --git a/docs/guides/concepts/frontend/javascript.rst b/docs/concepts/frontend/javascript.rst similarity index 100% rename from docs/guides/concepts/frontend/javascript.rst rename to docs/concepts/frontend/javascript.rst diff --git a/docs/guides/concepts/frontend/static_assets.rst b/docs/concepts/frontend/static_assets.rst similarity index 100% rename from docs/guides/concepts/frontend/static_assets.rst rename to docs/concepts/frontend/static_assets.rst diff --git a/docs/guides/concepts/frontend/styling.rst b/docs/concepts/frontend/styling.rst similarity index 100% rename from docs/guides/concepts/frontend/styling.rst rename to docs/concepts/frontend/styling.rst diff --git a/docs/guides/concepts/index.rst b/docs/concepts/index.rst similarity index 100% rename from docs/guides/concepts/index.rst rename to docs/concepts/index.rst diff --git a/docs/guides/concepts/testing/test_pyramid.png b/docs/concepts/testing/test_pyramid.png similarity index 100% rename from docs/guides/concepts/testing/test_pyramid.png rename to docs/concepts/testing/test_pyramid.png diff --git a/docs/guides/concepts/testing/testing.rst b/docs/concepts/testing/testing.rst similarity index 100% rename from docs/guides/concepts/testing/testing.rst rename to docs/concepts/testing/testing.rst diff --git a/docs/guides/conf.py b/docs/conf.py similarity index 100% rename from docs/guides/conf.py rename to docs/conf.py diff --git a/docs/guides/extensions/tinymce_plugins.rst b/docs/extensions/tinymce_plugins.rst similarity index 100% rename from docs/guides/extensions/tinymce_plugins.rst rename to docs/extensions/tinymce_plugins.rst diff --git a/docs/guides/__init__.py b/docs/guides/__init__.py deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/guides/hooks/events.rst b/docs/hooks/events.rst similarity index 100% rename from docs/guides/hooks/events.rst rename to docs/hooks/events.rst diff --git a/docs/guides/hooks/filters.rst b/docs/hooks/filters.rst similarity index 100% rename from docs/guides/hooks/filters.rst rename to docs/hooks/filters.rst diff --git a/docs/guides/hooks/index.rst b/docs/hooks/index.rst similarity index 100% rename from docs/guides/hooks/index.rst rename to docs/hooks/index.rst diff --git a/docs/guides/how-tos/celery.rst b/docs/how-tos/celery.rst similarity index 100% rename from docs/guides/how-tos/celery.rst rename to docs/how-tos/celery.rst diff --git a/docs/guides/how-tos/index.rst b/docs/how-tos/index.rst similarity index 100% rename from docs/guides/how-tos/index.rst rename to docs/how-tos/index.rst diff --git a/docs/guides/index.rst b/docs/index.rst similarity index 100% rename from docs/guides/index.rst rename to docs/index.rst diff --git a/docs/guides/make.bat b/docs/make.bat similarity index 100% rename from docs/guides/make.bat rename to docs/make.bat diff --git a/docs/guides/redirects.txt b/docs/redirects.txt similarity index 100% rename from docs/guides/redirects.txt rename to docs/redirects.txt diff --git a/docs/guides/references/docstrings/cms_index.rst b/docs/references/docstrings/cms_index.rst similarity index 100% rename from docs/guides/references/docstrings/cms_index.rst rename to docs/references/docstrings/cms_index.rst diff --git a/docs/guides/references/docstrings/common_djangoapps.rst b/docs/references/docstrings/common_djangoapps.rst similarity index 100% rename from docs/guides/references/docstrings/common_djangoapps.rst rename to docs/references/docstrings/common_djangoapps.rst diff --git a/docs/guides/references/docstrings/common_index.rst b/docs/references/docstrings/common_index.rst similarity index 100% rename from docs/guides/references/docstrings/common_index.rst rename to docs/references/docstrings/common_index.rst diff --git a/docs/guides/references/docstrings/index.rst b/docs/references/docstrings/index.rst similarity index 100% rename from docs/guides/references/docstrings/index.rst rename to docs/references/docstrings/index.rst diff --git a/docs/guides/references/docstrings/lms_index.rst b/docs/references/docstrings/lms_index.rst similarity index 100% rename from docs/guides/references/docstrings/lms_index.rst rename to docs/references/docstrings/lms_index.rst diff --git a/docs/guides/references/featuretoggles.rst b/docs/references/featuretoggles.rst similarity index 100% rename from docs/guides/references/featuretoggles.rst rename to docs/references/featuretoggles.rst diff --git a/docs/guides/references/index.rst b/docs/references/index.rst similarity index 100% rename from docs/guides/references/index.rst rename to docs/references/index.rst diff --git a/docs/guides/references/lms_apis.rst b/docs/references/lms_apis.rst similarity index 100% rename from docs/guides/references/lms_apis.rst rename to docs/references/lms_apis.rst diff --git a/docs/guides/references/settings.rst b/docs/references/settings.rst similarity index 100% rename from docs/guides/references/settings.rst rename to docs/references/settings.rst diff --git a/docs/guides/studio_oauth.rst b/docs/studio_oauth.rst similarity index 100% rename from docs/guides/studio_oauth.rst rename to docs/studio_oauth.rst diff --git a/docs/guides/v1_sass_pipeline.webp b/docs/v1_sass_pipeline.webp similarity index 100% rename from docs/guides/v1_sass_pipeline.webp rename to docs/v1_sass_pipeline.webp From a586c3bab0a2551b6db4aa0ee1f781831f199c49 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Tue, 18 Jul 2023 14:33:26 -0400 Subject: [PATCH 3/5] fix: Update openapi yaml location. --- docs/references/lms_apis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/lms_apis.rst b/docs/references/lms_apis.rst index b2a95489ed..7c77b47e50 100644 --- a/docs/references/lms_apis.rst +++ b/docs/references/lms_apis.rst @@ -4,4 +4,4 @@ LMS APIs The LMS currently has the following API Endpoints. -.. openapi:: ../../lms-openapi.yaml +.. openapi:: ../lms-openapi.yaml From f32c938961b6660bd87b5b4789bec9a01dcd1bec Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Tue, 18 Jul 2023 15:41:34 -0400 Subject: [PATCH 4/5] fix: Update conf paths to match the new docs layout. --- docs/conf.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0135285246..33225f5719 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,12 +16,12 @@ import git from path import Path -root = Path('../..').abspath() +root = Path('..').abspath() # Hack the PYTHONPATH to match what LMS and Studio use so all the code # can be successfully imported sys.path.insert(0, root) -sys.path.append(root / "docs/guides") +sys.path.append(root / "docs") # Use a settings module that allows all LMS and Studio code to be imported @@ -74,9 +74,8 @@ rediraffe_branch = 'origin/master' # 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__), "..", "..") -) +edxplatform_source_path = root + try: edx_platform_version = git.Repo(search_parent_directories=True).head.object.hexsha except git.InvalidGitRepositoryError: @@ -136,7 +135,7 @@ html_favicon = "https://logos.openedx.org/open-edx-favicon.ico" html_theme_options = { "repository_url": "https://github.com/openedx/edx-platform", "repository_branch": "master", - "path_to_docs": "docs/guides", + "path_to_docs": "docs", "home_page_in_toc": True, "use_repository_button": True, "use_issues_button": True, @@ -308,7 +307,7 @@ def on_init(app): # lint-amnesty, pylint: disable=redefined-outer-name, unused- Read the Docs won't run tox or custom shell commands, so we need this to avoid checking in the generated reStructuredText files. """ - docs_path = root / 'docs' / 'guides' + docs_path = root / 'docs' apidoc_path = 'sphinx-apidoc' if hasattr(sys, 'real_prefix'): # Check to see if we are in a virtualenv # If we are, assemble the path manually From de6639a85f43768ae15374c80255eded359326a6 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Tue, 18 Jul 2023 16:04:57 -0400 Subject: [PATCH 5/5] docs: Update .readthedocs.yml to point to the sphinx config. Now that there is only one sphinx project, the RTD config can be more specific and stop relying on the old style config which is about to be deprecated. --- .readthedocs.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 1ba26f8d58..cf3f80aec8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -5,6 +5,9 @@ build: tools: python: "3.8" +sphinx: + configuration: source/conf.py + python: install: - requirements: "requirements/edx/doc.txt"