Merge pull request #32780 from openedx/feanil/unify_docs

feanil/unify docs

.readthedocs.yaml

@@ -5,6 +5,9 @@ build:
   tools:
     python: "3.8"
 
+sphinx:
+  configuration: source/conf.py
+
 python:
   install:
   - requirements: "requirements/edx/doc.txt"

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

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

docs/technical/.gitignore

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

docs/technical/Makefile

@@ -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)

docs/technical/conf.py

@@ -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": """
-        <a rel="license" href="https://creativecommons.org/licenses/by-sa/4.0/">
-            <img
-                alt="Creative Commons License"
-                style="border-width:0"
-                src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png"/>
-        </a>
-        <br>
-        These works by
-            <a
-                xmlns:cc="https://creativecommons.org/ns#"
-                href="https://openedx.org"
-                property="cc:attributionName"
-                rel="cc:attributionURL"
-            >Axim Collaborative, Inc</a>
-        are licensed under a
-            <a
-                rel="license"
-                href="https://creativecommons.org/licenses/by-sa/4.0/"
-            >Creative Commons Attribution-ShareAlike 4.0 International License</a>.
-    """,
-}

docs/technical/featuretoggles.rst

@@ -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::

docs/technical/index.rst

@@ -1,9 +0,0 @@
-====================================
-``edx-platform`` technical reference
-====================================
-
-This is the technical documentation reference for edx-platform.
-
-.. toctree::
-    settings
-    featuretoggles

docs/technical/settings.rst

@@ -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 <featuretoggles>` section.
-
-LMS settings
-------------
-
-.. settings::
-    :folder_path: lms/envs/common.py
-
-CMS settings
-------------
-
-.. settings::
-    :folder_path: cms/envs/common.py