Merge pull request #32614 from openedx/feanil/reorg_guides

feanil/reorg guides
openedx · Jul 12, 2023 · 595501f · 595501f
2 parents f60735a + eba2856
commit 595501f
Show file tree

Hide file tree

Showing 25 changed files with 91 additions and 20 deletions.
diff --git a/docs/guides/.gitignore b/docs/guides/.gitignore
@@ -1,5 +1,6 @@
 _build
-cms
-common
-lms
-openedx
+references/docstrings/cms
+references/docstrings/common
+references/docstrings/lms
+references/docstrings/openedx
+references/docstrings/xmodule
diff --git a/docs/guides/extension_points.rst → docs/guides/concepts/extension_points.rst b/docs/guides/extension_points.rst → docs/guides/concepts/extension_points.rst
diff --git a/docs/guides/frontend/bootstrap.rst → docs/guides/concepts/frontend/bootstrap.rst b/docs/guides/frontend/bootstrap.rst → docs/guides/concepts/frontend/bootstrap.rst
diff --git a/docs/guides/frontend/javascript.rst → docs/guides/concepts/frontend/javascript.rst b/docs/guides/frontend/javascript.rst → docs/guides/concepts/frontend/javascript.rst
diff --git a/docs/guides/frontend/static_assets.rst → ...uides/concepts/frontend/static_assets.rst b/docs/guides/frontend/static_assets.rst → ...uides/concepts/frontend/static_assets.rst
diff --git a/docs/guides/frontend/styling.rst → docs/guides/concepts/frontend/styling.rst b/docs/guides/frontend/styling.rst → docs/guides/concepts/frontend/styling.rst
diff --git a/docs/guides/guides.rst → docs/guides/concepts/index.rst b/docs/guides/guides.rst → docs/guides/concepts/index.rst
@@ -1,5 +1,5 @@
-Guides
-******
+Concepts and Guides
+###################
 
 .. toctree::
     :maxdepth: 2

diff --git a/docs/guides/testing/test_pyramid.png → .../guides/concepts/testing/test_pyramid.png b/docs/guides/testing/test_pyramid.png → .../guides/concepts/testing/test_pyramid.png
diff --git a/docs/guides/testing/testing.rst → docs/guides/concepts/testing/testing.rst b/docs/guides/testing/testing.rst → docs/guides/concepts/testing/testing.rst
diff --git a/docs/guides/conf.py b/docs/guides/conf.py
@@ -62,6 +62,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
     'sphinxcontrib.openapi',
+    'sphinx_design',
     'code_annotations.contrib.sphinx.extensions.featuretoggles',
     'code_annotations.contrib.sphinx.extensions.settings',
 ]
@@ -272,10 +273,11 @@
 # run sphinx-apidoc against and the directories under "docs" in which to store
 # the generated *.rst files
 modules = {
-    'cms': 'cms',
-    'lms': 'lms',
-    'openedx': 'openedx',
-    'xmodule': 'xmodule',
+    'cms': 'references/docstrings/cms',
+    'lms': 'references/docstrings/lms',
+    'openedx': 'references/docstrings/openedx',
+    'common': 'references/docstrings/common',
+    'xmodule': 'references/docstrings/xmodule',
 }
 
 

diff --git a/docs/guides/celery.rst → docs/guides/how-tos/celery.rst b/docs/guides/celery.rst → docs/guides/how-tos/celery.rst
diff --git a/docs/guides/how-tos/index.rst b/docs/guides/how-tos/index.rst
@@ -0,0 +1,8 @@
+"How-To" Guides
+###############
+
+
+.. toctree::
+   :glob:
+
+   *
diff --git a/docs/guides/index.rst b/docs/guides/index.rst
@@ -24,17 +24,65 @@ locations.
 .. toctree::
     :maxdepth: 1
 
-    lms_apis
-    guides
     docstrings/docstrings
-    celery
-    settings
-    featuretoggles
+
+.. toctree::
+    :hidden:
+
+    how-tos/index
+    references/index
+    concepts/index
+
+.. grid:: 1 2 2 2
+   :gutter: 3
+   :padding: 0
+
+   .. grid-item-card:: How-tos
+      :class-card: sd-shadow-md sd-p-2
+      :class-footer: sd-border-0
+
+      * :doc:`how-tos/celery`
+      +++
+      .. button-ref:: how-tos/index
+         :color: primary
+         :outline:
+         :expand:
+
+   .. grid-item-card:: Referencs
+      :class-card: sd-shadow-md sd-p-2
+      :class-footer: sd-border-0
+
+      * :doc:`references/lms_apis`
+      * :doc:`references/settings`
+      * :doc:`references/featuretoggles`
+      +++
+      .. button-ref:: references/index
+         :color: primary
+         :outline:
+         :expand:
+
+   .. grid-item-card:: Concepts
+      :class-card: sd-shadow-md sd-p-2
+      :class-footer: sd-border-0
+
+      * :doc:`concepts/extension_points`
+      * :doc:`concepts/testing/testing`
+      * :doc:`concepts/frontend/javascript`
+      +++
+      .. button-ref:: concepts/index
+         :color: primary
+         :outline:
+         :expand:
 
 
 Change History
 **************
 
+* Jun 30, 2023
+
+  * Added API, Feature Toggle and Settings docs.
+  * Re-organized how the docs are laid out.
+
 * December, 2020: Added documentation about new protocols for writing celery tasks.
 
 * April, 2019: API and repository-specific documentation builds resumed.

diff --git a/docs/guides/docstrings/cms_index.rst → ...uides/references/docstrings/cms_index.rst b/docs/guides/docstrings/cms_index.rst → ...uides/references/docstrings/cms_index.rst
diff --git a/docs/guides/docstrings/common_djangoapps.rst → ...ferences/docstrings/common_djangoapps.rst b/docs/guides/docstrings/common_djangoapps.rst → ...ferences/docstrings/common_djangoapps.rst
diff --git a/docs/guides/docstrings/common_index.rst → ...es/references/docstrings/common_index.rst b/docs/guides/docstrings/common_index.rst → ...es/references/docstrings/common_index.rst
@@ -10,5 +10,4 @@ package.
 .. toctree::
     :maxdepth: 2
 
-    common_djangoapps
-    common_lib
+    common/common
diff --git a/docs/guides/docstrings/docstrings.rst → docs/guides/references/docstrings/index.rst b/docs/guides/docstrings/docstrings.rst → docs/guides/references/docstrings/index.rst
diff --git a/docs/guides/docstrings/lms_index.rst → ...uides/references/docstrings/lms_index.rst b/docs/guides/docstrings/lms_index.rst → ...uides/references/docstrings/lms_index.rst
diff --git a/docs/guides/featuretoggles.rst → docs/guides/references/featuretoggles.rst b/docs/guides/featuretoggles.rst → docs/guides/references/featuretoggles.rst
diff --git a/docs/guides/references/index.rst b/docs/guides/references/index.rst
@@ -0,0 +1,9 @@
+References
+##########
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *
+    docstrings/index
diff --git a/docs/guides/lms_apis.rst → docs/guides/references/lms_apis.rst b/docs/guides/lms_apis.rst → docs/guides/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/settings.rst → docs/guides/references/settings.rst b/docs/guides/settings.rst → docs/guides/references/settings.rst
diff --git a/requirements/edx/development.in b/requirements/edx/development.in
@@ -12,11 +12,10 @@
 
 -r ../pip-tools.txt                     # pip-tools and its dependencies, for managing requirements files
 -r testing.txt                          # Dependencies for running the various test suites
+-r doc.txt                              # Dependencies for building the documentation locally.
 
 click                                   # Used for perf_tests utilities in modulestore
 django-debug-toolbar                    # A set of panels that display debug information about the current request/response
-sphinx-book-theme                       # Documentation theme
 mypy                                    # static type checking
 pywatchman                              # More efficient checking for runserver reload trigger events
-sphinxcontrib-openapi[markdown]         # OpenAPI (fka Swagger) spec renderer for Sphinx
 vulture                                 # Detects possible dead/unused code, used in scripts/find-dead-code.sh
diff --git a/requirements/edx/doc.in b/requirements/edx/doc.in
@@ -5,3 +5,5 @@ code-annotations          # provides annotations for certain documentation
 sphinx-book-theme         # Common theme for all Open edX projects
 gitpython                 # fetch git repo information
 Sphinx                    # Documentation builder
+sphinx-design             # provides various responsive web-components
+sphinxcontrib-openapi[markdown] # Be able to render openapi schema in a sphinx project
diff --git a/requirements/edx/doc.txt b/requirements/edx/doc.txt
@@ -82,8 +82,11 @@ sphinx==6.2.1
     #   -r requirements/edx/doc.in
     #   pydata-sphinx-theme
     #   sphinx-book-theme
+    #   sphinx-design
 sphinx-book-theme==1.0.1
     # via -r requirements/edx/doc.in
+sphinx-design==0.4.1
+    # via -r requirements/edx/doc.in
 sphinxcontrib-applehelp==1.0.4
     # via sphinx
 sphinxcontrib-devhelp==1.0.2