From 0167b09a3b6d184ee38c049845e9a74ec3ea0308 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 29 Jun 2023 16:45:09 -0400 Subject: [PATCH 1/6] docs: Add the new sphinx-design extension. This gives us the abuliity to add some nice responsive web components to our docs. In particular girds and cards. --- docs/guides/conf.py | 1 + requirements/edx/doc.in | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/guides/conf.py b/docs/guides/conf.py index 221383b53b..aa8b0bb073 100644 --- a/docs/guides/conf.py +++ b/docs/guides/conf.py @@ -62,6 +62,7 @@ extensions = [ 'sphinx.ext.mathjax', 'sphinx.ext.napoleon', 'sphinxcontrib.openapi', + 'sphinx_design', 'code_annotations.contrib.sphinx.extensions.featuretoggles', 'code_annotations.contrib.sphinx.extensions.settings', ] diff --git a/requirements/edx/doc.in b/requirements/edx/doc.in index bd0f4f9fc5..d86264b534 100644 --- a/requirements/edx/doc.in +++ b/requirements/edx/doc.in @@ -5,3 +5,4 @@ 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 From 8682d1d95a23cfe24ddb3f926a6b9b8fc1050ddf Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 29 Jun 2023 16:49:49 -0400 Subject: [PATCH 2/6] chore: Run `make compile-requirements` to add sphinx-design. --- requirements/edx/doc.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/requirements/edx/doc.txt b/requirements/edx/doc.txt index ca8a55c61c..7eaf5ad66e 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 From bdf9870cf7f1b77f015b933df0d1c2c84d016640 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 29 Jun 2023 17:54:16 -0400 Subject: [PATCH 3/6] docs: Move how-tos and references to sub-folders. --- docs/guides/{ => how-tos}/celery.rst | 0 docs/guides/how-tos/index.rst | 8 ++++ docs/guides/index.rst | 40 ++++++++++++++++--- .../{ => references}/featuretoggles.rst | 0 docs/guides/references/index.rst | 8 ++++ docs/guides/{ => references}/lms_apis.rst | 2 +- docs/guides/{ => references}/settings.rst | 0 7 files changed, 52 insertions(+), 6 deletions(-) rename docs/guides/{ => how-tos}/celery.rst (100%) create mode 100644 docs/guides/how-tos/index.rst rename docs/guides/{ => references}/featuretoggles.rst (100%) create mode 100644 docs/guides/references/index.rst rename docs/guides/{ => references}/lms_apis.rst (66%) rename docs/guides/{ => references}/settings.rst (100%) 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 0000000000..cb85be6be4 --- /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 49ce6eb8cb..d8e83e8b82 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -24,12 +24,42 @@ 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: Change History 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 0000000000..7d7821ed23 --- /dev/null +++ b/docs/guides/references/index.rst @@ -0,0 +1,8 @@ +References +########## + +.. toctree:: + :maxdepth: 1 + :glob: + + * 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 7c77b47e50..b2a95489ed 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 From 50f164a6ff37063bb38f519211269ea61c070c96 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 29 Jun 2023 17:56:49 -0400 Subject: [PATCH 4/6] docs: Rename guides to concepts. The guides map pretty closely to the concept docs in diataxis so rename them as such to align to the standard naming we're moving to. --- .../{ => concepts}/extension_points.rst | 0 .../{ => concepts}/frontend/bootstrap.rst | 0 .../{ => concepts}/frontend/javascript.rst | 0 .../{ => concepts}/frontend/static_assets.rst | 0 .../{ => concepts}/frontend/styling.rst | 0 .../guides/{guides.rst => concepts/index.rst} | 4 ++-- .../{ => concepts}/testing/test_pyramid.png | Bin .../guides/{ => concepts}/testing/testing.rst | 0 docs/guides/index.rst | 18 ++++++++++++++++++ 9 files changed, 20 insertions(+), 2 deletions(-) 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/{guides.rst => concepts/index.rst} (80%) rename docs/guides/{ => concepts}/testing/test_pyramid.png (100%) rename docs/guides/{ => concepts}/testing/testing.rst (100%) 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 5eb3aa5e27..01f9250379 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/index.rst b/docs/guides/index.rst index d8e83e8b82..59d4934146 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -61,10 +61,28 @@ locations. :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. From dcebcc4d0d6364d64cbf7da324e5013828941fba Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Fri, 30 Jun 2023 09:33:50 -0400 Subject: [PATCH 5/6] docs: Make the generated docs visible. There is still a lot of improvements that could be made to make the generated docs better organized. However, before this change we were generating the docs but they weren't in the doc tree so you couldn't actually browse to them. So we fix that first so that we can start getting feedback about how to organize them. --- docs/guides/.gitignore | 9 +++++---- docs/guides/conf.py | 9 +++++---- docs/guides/{ => references}/docstrings/cms_index.rst | 0 .../{ => references}/docstrings/common_djangoapps.rst | 0 docs/guides/{ => references}/docstrings/common_index.rst | 3 +-- .../docstrings.rst => references/docstrings/index.rst} | 0 docs/guides/{ => references}/docstrings/lms_index.rst | 0 docs/guides/references/index.rst | 1 + 8 files changed, 12 insertions(+), 10 deletions(-) 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 (90%) rename docs/guides/{docstrings/docstrings.rst => references/docstrings/index.rst} (100%) rename docs/guides/{ => references}/docstrings/lms_index.rst (100%) diff --git a/docs/guides/.gitignore b/docs/guides/.gitignore index a77dad836c..3d5538b288 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/conf.py b/docs/guides/conf.py index aa8b0bb073..d4d8dc7897 100644 --- a/docs/guides/conf.py +++ b/docs/guides/conf.py @@ -273,10 +273,11 @@ autodoc_mock_imports = [ # 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/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 f2c6d9a7a9..ce3e05c45a 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/references/index.rst b/docs/guides/references/index.rst index 7d7821ed23..d1a1af3986 100644 --- a/docs/guides/references/index.rst +++ b/docs/guides/references/index.rst @@ -6,3 +6,4 @@ References :glob: * + docstrings/index From eba2856293ae929ab75f68d2cd2e80498fe40494 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Wed, 12 Jul 2023 14:27:23 -0400 Subject: [PATCH 6/6] build: Re-org docs deps. Some doc buildig deps were in development.in explicitly while others weren't. Update development.in to pull in doc.txt and then remove direct additions of the doc requirements from development.in --- requirements/edx/development.in | 3 +-- requirements/edx/doc.in | 1 + 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements/edx/development.in b/requirements/edx/development.in index 6f443efe49..ffdc299edd 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 d86264b534..c4bef4d4fd 100644 --- a/requirements/edx/doc.in +++ b/requirements/edx/doc.in @@ -6,3 +6,4 @@ 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