TE-2850 Resume RTD doc builds (openedx#19910)

.gitignore

@@ -143,3 +143,10 @@ dist
 
 # Locally generated PII reports
 pii_report
+
+# Local documentation builds
+docs/_build
+docs/cms
+docs/common
+docs/lms
+docs/openedx

Makefile

@@ -1,5 +1,5 @@
 # Do things in edx-platform
-.PHONY: clean extract_translations help pull pull_translations push_translations requirements shell upgrade
+.PHONY: clean docs extract_translations help pull pull_translations push_translations requirements shell upgrade
 
 # Careful with mktemp syntax: it has to work on Mac and Ubuntu, which have differences.
 PRIVATE_FILES := $(shell mktemp -u /tmp/private_files.XXXXXX)
@@ -18,6 +18,10 @@ clean: ## archive and delete most git-ignored files
 	tar xf $(PRIVATE_FILES)
 	rm $(PRIVATE_FILES)
 
+docs: ## build the developer documentation for this repository
+	rm -rf docs/_build docs/cms docs/common docs/lms docs/openedx
+	cd docs; make html
+
 extract_translations: ## extract localizable strings from sources
 	i18n_tool extract -v
 

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+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/cms_index.rst

@@ -0,0 +1,14 @@
+cms
+***
+
+The ``cms`` (course management system) directory in edx-platform is home to
+the code needed for the Course Authoring Studio which is not also needed for
+the LMS.
+
+.. toctree::
+    :maxdepth: 2
+
+    cms/modules
+    cms/djangoapps/contentstore/modules
+    cms/djangoapps/course_creators/modules
+    cms/djangoapps/xblock_config/modules

docs/common_djangoapps.rst

@@ -0,0 +1,25 @@
+common/djangoapps
+*****************
+
+This directory contains Django applications intended to be used in both the
+LMS and Studio.
+
+.. toctree::
+    :maxdepth: 2
+
+    common/djangoapps/course_action_state/modules
+    common/djangoapps/course_modes/modules
+    common/djangoapps/database_fixups/modules
+    common/djangoapps/django_comment_common/modules
+    common/djangoapps/edxmako/modules
+    common/djangoapps/enrollment/modules
+    common/djangoapps/entitlements/modules
+    common/djangoapps/microsite_configuration/modules
+    common/djangoapps/pipeline_mako/modules
+    common/djangoapps/static_replace/modules
+    common/djangoapps/status/modules
+    common/djangoapps/student/modules
+    common/djangoapps/third_party_auth/modules
+    common/djangoapps/track/modules
+    common/djangoapps/util/modules
+    common/djangoapps/xblock_django/modules

docs/common_index.rst

@@ -0,0 +1,14 @@
+common
+******
+
+The ``common`` directory in edx-platform is home to an assortment of packages
+used by the LMS and Studio.  This is a legacy code organization decision, and
+it is currently intended that most of the code here will eventually either be
+moved into the ``openedx`` package or broken out into a separately installed
+package.
+
+.. toctree::
+    :maxdepth: 2
+
+    common_djangoapps
+    common_lib

docs/common_lib.rst

@@ -0,0 +1,16 @@
+common/lib
+**********
+
+This directory contains libraries which are installed locally so they can be
+imported by name with no package hierarchy.  They will most likely be split
+out from edx-platform into separate packages at some point.
+
+.. toctree::
+    :maxdepth: 2
+
+    common/lib/calc/modules
+    common/lib/capa/modules
+    common/lib/chem/modules
+    common/lib/safe_lxml/modules
+    common/lib/symmath/modules
+    common/lib/xmodule/modules