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" 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 97% rename from docs/guides/conf.py rename to docs/conf.py index 0135285246..33225f5719 100644 --- a/docs/guides/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 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 66% rename from docs/guides/references/lms_apis.rst rename to docs/references/lms_apis.rst index b2a95489ed..7c77b47e50 100644 --- a/docs/guides/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 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/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 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