diff --git a/docs/guides/.gitignore b/docs/guides/.gitignore index a77dad836c2..3d5538b288c 100644 --- 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 b/docs/guides/concepts/extension_points.rst similarity index 100% rename from docs/guides/extension_points.rst rename to docs/guides/concepts/extension_points.rst diff --git a/docs/guides/frontend/bootstrap.rst b/docs/guides/concepts/frontend/bootstrap.rst similarity index 100% rename from docs/guides/frontend/bootstrap.rst rename to docs/guides/concepts/frontend/bootstrap.rst diff --git a/docs/guides/frontend/javascript.rst b/docs/guides/concepts/frontend/javascript.rst similarity index 100% rename from docs/guides/frontend/javascript.rst rename to docs/guides/concepts/frontend/javascript.rst diff --git a/docs/guides/frontend/static_assets.rst b/docs/guides/concepts/frontend/static_assets.rst similarity index 100% rename from docs/guides/frontend/static_assets.rst rename to docs/guides/concepts/frontend/static_assets.rst diff --git a/docs/guides/frontend/styling.rst b/docs/guides/concepts/frontend/styling.rst similarity index 100% rename from docs/guides/frontend/styling.rst rename to docs/guides/concepts/frontend/styling.rst diff --git a/docs/guides/guides.rst b/docs/guides/concepts/index.rst similarity index 80% rename from docs/guides/guides.rst rename to docs/guides/concepts/index.rst index 5eb3aa5e270..01f92503795 100644 --- a/docs/guides/guides.rst +++ b/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 b/docs/guides/concepts/testing/test_pyramid.png similarity index 100% rename from docs/guides/testing/test_pyramid.png rename to docs/guides/concepts/testing/test_pyramid.png diff --git a/docs/guides/testing/testing.rst b/docs/guides/concepts/testing/testing.rst similarity index 100% rename from docs/guides/testing/testing.rst rename to docs/guides/concepts/testing/testing.rst diff --git a/docs/guides/conf.py b/docs/guides/conf.py index 221383b53b1..d4d8dc78970 100644 --- 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 b/docs/guides/how-tos/celery.rst similarity index 100% rename from docs/guides/celery.rst rename to docs/guides/how-tos/celery.rst diff --git a/docs/guides/how-tos/index.rst b/docs/guides/how-tos/index.rst new file mode 100644 index 00000000000..cb85be6be4b --- /dev/null +++ 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 index 49ce6eb8cb8..59d4934146c 100644 --- 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 b/docs/guides/references/docstrings/cms_index.rst similarity index 100% rename from docs/guides/docstrings/cms_index.rst rename to docs/guides/references/docstrings/cms_index.rst diff --git a/docs/guides/docstrings/common_djangoapps.rst b/docs/guides/references/docstrings/common_djangoapps.rst similarity index 100% rename from docs/guides/docstrings/common_djangoapps.rst rename to docs/guides/references/docstrings/common_djangoapps.rst diff --git a/docs/guides/docstrings/common_index.rst b/docs/guides/references/docstrings/common_index.rst similarity index 90% rename from docs/guides/docstrings/common_index.rst rename to docs/guides/references/docstrings/common_index.rst index f2c6d9a7a96..ce3e05c45a4 100644 --- a/docs/guides/docstrings/common_index.rst +++ b/docs/guides/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 b/docs/guides/references/docstrings/index.rst similarity index 100% rename from docs/guides/docstrings/docstrings.rst rename to docs/guides/references/docstrings/index.rst diff --git a/docs/guides/docstrings/lms_index.rst b/docs/guides/references/docstrings/lms_index.rst similarity index 100% rename from docs/guides/docstrings/lms_index.rst rename to docs/guides/references/docstrings/lms_index.rst diff --git a/docs/guides/featuretoggles.rst b/docs/guides/references/featuretoggles.rst similarity index 100% rename from docs/guides/featuretoggles.rst rename to docs/guides/references/featuretoggles.rst diff --git a/docs/guides/references/index.rst b/docs/guides/references/index.rst new file mode 100644 index 00000000000..d1a1af3986c --- /dev/null +++ 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 b/docs/guides/references/lms_apis.rst similarity index 66% rename from docs/guides/lms_apis.rst rename to docs/guides/references/lms_apis.rst index 7c77b47e500..b2a95489edf 100644 --- a/docs/guides/lms_apis.rst +++ b/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 b/docs/guides/references/settings.rst similarity index 100% rename from docs/guides/settings.rst rename to docs/guides/references/settings.rst diff --git a/requirements/edx/development.in b/requirements/edx/development.in index 6f443efe49f..ffdc299eddd 100644 --- 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 index bd0f4f9fc5e..c4bef4d4fd7 100644 --- 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 index ca8a55c61c5..7eaf5ad66e0 100644 --- 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