Fix Read the Docs build, add "make serve_docs", fix many build warnings by bmtcril · Pull Request #557 · openedx/openedx-events

bmtcril · 2026-03-31T14:38:42Z

Description

Fixes readthedoc builds due to outdated, unused package. Adds ability to test doc changes live locally. Fixes numerous build warnings.

Supporting information

PR tests were failing on building docs with WARNING: the sphinxcontrib.contentui extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit

#555
https://app.readthedocs.org/projects/openedx-events/builds/32043156/

Testing instructions

If this passes tests, that's pretty good. 😄 Checking out the branch and running make serve_docs should allow you to test the Makefile change.

Deadline

ASAP as it's blocking other development in this repo.

This package was unused, hasn't been updated in years, and is now failing RtD builds due to a warning. Removed the requirement, Sphinx conf reference to it, and re-ran make upgrade.

Regular "make docs" does a build that works for RtD but viewing it locally doesn't use the theme / can't find static assets. This command allows working in the docs where you can actually see the finished product.

A number of warnings were occurring at build time that people probably don't normally see. I cleaned these up so the build is up to date, no deprecation or other warnings.

bmtcril · 2026-03-31T14:39:11Z

 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinxcontrib.contentui',


Removing this is the most important change here, almost everything else is single quotes to double quotes.

bmtcril · 2026-03-31T14:41:15Z

 include README.rst
 include requirements/base.in
-recursive-include openedx_events *.html *.png *.gif *.js *.css *.jpg *.jpeg *.svg *.py
+recursive-include openedx_events *.py


These caused warnings about none of those file types existing to copy.

warning: no files found matching '*.png' under directory 'openedx_authz' warning: no files found matching '*.gif' under directory 'openedx_authz' warning: no files found matching '*.js' under directory 'openedx_authz' warning: no files found matching '*.css' under directory 'openedx_authz' warning: no files found matching '*.jpg' under directory 'openedx_authz' warning: no files found matching '*.jpeg' under directory 'openedx_authz' warning: no files found matching '*.svg' under directory 'openedx_authz'

bmtcril · 2026-03-31T14:42:12Z

 line_length = 120
 multi_line_output = 3
-
-[wheel]


This was throwing a warning:

The [wheel] section is deprecated. Use [bdist_wheel] instead. /tmp/build-env-bjhgbisv/lib/python3.12/site-packages/setuptools/_distutils/cmd.py:119: SetuptoolsDeprecationWarning: bdist_wheel.universal is deprecated !! ******************************************************************************** With Python 2.7 end-of-life, support for building universal wheels (i.e., wheels that support both Python 2 and Python 3) is being obviated. Please discontinue using this option, or if you still need it, file an issue with pypa/setuptools describing your use case. This deprecation is overdue, please update your project and remove deprecated calls to avoid build errors in the future. ******************************************************************************** !! self.finalize_options()

bmtcril · 2026-03-31T14:44:03Z

+    author="edX",
+    author_email="oscm@edx.org",
+    url="https://github.com/openedx/openedx-events",
+    packages=find_packages(


Fixes many warnings like:

/tmp/build-env-bjhgbisv/lib/python3.12/site-packages/setuptools/command/build_py.py:215: _Warning: Package 'openedx_authz.engine.config' is absent from the `packages` configuration. !! ******************************************************************************** ############################ # Package would be ignored # ############################ Python recognizes 'openedx_authz.engine.config' as an importable package[^1], but it is absent from setuptools' `packages` configuration. ... You can read more about "package discovery" on setuptools documentation page: - https://setuptools.pypa.io/en/latest/userguide/package_discovery.html

bmtcril · 2026-03-31T14:44:50Z

    classifiers=[
-        'Development Status :: 3 - Alpha',
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: Apache Software License',


This is the only change in this block, fixes warning:

SetuptoolsDeprecationWarning: License classifiers are deprecated. !! ******************************************************************************** Please consider removing the following classifiers in favor of a SPDX license expression: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+) See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for details. ********************************************************************************

BryanttV

Thanks for this @bmtcril! Just a minor comment

BryanttV · 2026-03-31T19:07:34Z

 	tox -e docs
 	$(BROWSER)docs/_build/html/index.html

+serve_docs: ## serve the built docs locally to preview the RtD in the browser with theme working


Can we use a different port instead of 8000? I tried running the command, but since I had a Tutor environment running, it failed because the port was already in use.

Moved it to 9898, which probably conflicts with something else but hopefully something less important 🥲

openedx_events/tests/utils.py was excluded from the installed package by the exclude=["*tests"] in setup.py (introduced in #557), breaking downstream consumers that import from openedx_events.tests.utils. Move the public test utilities to openedx_events/testing.py so they are included in the installed package. New import paths: from openedx_events.testing import FreezeSignalCacheMixin from openedx_events.testing import EventsIsolationMixin from openedx_events.testing import OpenEdxEventsTestMixin Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: restore all events in OpenEdxEventsTestMixin.tearDownClass OpenEdxEventsTestMixin.setUpClass() disables all OpenEdX events then enables only those listed in ENABLED_OPENEDX_EVENTS, but had no corresponding tearDownClass to restore event state. This caused any events left disabled to remain disabled for subsequent test classes running in the same process. Add tearDownClass to re-enable all events so that test classes using this mixin do not leak disabled event state into other tests. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test: add tests for OpenEdxEventsTestMixin.tearDownClass event restoration Verify that tearDownClass re-enables all events so subsequent test classes running in the same process are not affected by the mixin's event isolation — the regression that motivated the tearDownClass fix. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * refactor: move test utilities to openedx_events.testing openedx_events/tests/utils.py was excluded from the installed package by the exclude=["*tests"] in setup.py (introduced in #557), breaking downstream consumers that import from openedx_events.tests.utils. Move the public test utilities to openedx_events/testing.py so they are included in the installed package. New import paths: from openedx_events.testing import FreezeSignalCacheMixin from openedx_events.testing import EventsIsolationMixin from openedx_events.testing import OpenEdxEventsTestMixin Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Tycho Hob added 3 commits March 31, 2026 10:32

docs: Remove sphinxcontrib-contentui from docs

bcf3914

This package was unused, hasn't been updated in years, and is now failing RtD builds due to a warning. Removed the requirement, Sphinx conf reference to it, and re-ran make upgrade.

feat: Add "make serve_docs" command

0061901

Regular "make docs" does a build that works for RtD but viewing it locally doesn't use the theme / can't find static assets. This command allows working in the docs where you can actually see the finished product.

chore: Fix build warnings

01321d6

A number of warnings were occurring at build time that people probably don't normally see. I cleaned these up so the build is up to date, no deprecation or other warnings.

bmtcril commented Mar 31, 2026

View reviewed changes

bmtcril changed the title ~~Bmtcril/fix docs and warnings~~ Fix Read the Docs build, add "make serve_docs", fix many build warnings Mar 31, 2026

bmtcril requested review from BryanttV and mariajgrimaldi March 31, 2026 14:46

BryanttV approved these changes Mar 31, 2026

View reviewed changes

fix: Make sphinx-autobuild use a non-tutor port

9f43ab8

bmtcril merged commit 20849f3 into main Mar 31, 2026
9 checks passed

bmtcril deleted the bmtcril/fix_docs_and_warnings branch March 31, 2026 20:06

feanil mentioned this pull request Apr 8, 2026

fix: restore all events in OpenEdxEventsTestMixin.tearDownClass #559

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix Read the Docs build, add "make serve_docs", fix many build warnings#557

Fix Read the Docs build, add "make serve_docs", fix many build warnings#557
bmtcril merged 4 commits intomainfrom
bmtcril/fix_docs_and_warnings

bmtcril commented Mar 31, 2026

Uh oh!

bmtcril Mar 31, 2026 •

edited

Loading

Uh oh!

bmtcril Mar 31, 2026

Uh oh!

bmtcril Mar 31, 2026

Uh oh!

bmtcril Mar 31, 2026

Uh oh!

bmtcril Mar 31, 2026

Uh oh!

BryanttV left a comment

Uh oh!

BryanttV Mar 31, 2026

Uh oh!

bmtcril Mar 31, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

bmtcril commented Mar 31, 2026

Description

Supporting information

Testing instructions

Deadline

Uh oh!

bmtcril Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bmtcril Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

bmtcril Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

bmtcril Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

bmtcril Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

BryanttV left a comment

Choose a reason for hiding this comment

Uh oh!

BryanttV Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

bmtcril Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bmtcril Mar 31, 2026 •

edited

Loading