edx-django-utils readthedocs is failing to build

[robrap]

Firm Name

2U

Urgency

Medium (< 2 weeks)

Problem/Request

The readthedocs build https://readthedocs.org/projects/edx-django-utils/ is failing for some reason.

Reasoning

It's broken.

[openedx-workflow-automation]

Thank you for your report! @openedx/axim-oncall will triage within a business day. Simple requests usually take 2-3 business days to resolve; more complex requests could take longer.

[sarina]

Hi @robrap - this should be an issue on the appropriate repo. As on-call I do not have the tools to fix this. The maintainer of that repo or someone with Docs knowledge can be asked to fix the issue.

[sarina]

@feanil is this something that could go on the docs backlog?

[feanil]

Yep, I'll add it there. @robrap The failing build output is here it looks like an issue with the requirements: https://readthedocs.org/projects/edx-django-utils/builds/20309157/

I can dig into it next week if you don't get to it before then.

[robrap]

@feanil: Others determined that it might be a Python 3.7 vs Python 3.8 issue. I wonder if you could switch this repo to use a new config file like https://github.com/openedx/edx-platform/blob/master/.readthedocs.yaml so we could self-manage fixing in the future.

I’m not sure if the config file is in the cookie-cutter, but the more of this in GitHub the less it is restricted to Axim fixing.

Thanks.

[robrap]

Becca is adding the appropriate config file in #303. If it automatically gets picked up by readthedocs, we’ll close this ticket. If not, a simple admin setting change in readthedocs to point to the new config file should be enough.

[rgraber]

If we want to set up readthedocs to fail on warning the way we do for open-edx-proposals, we'll need to fix a bunch of warnings that autodoc is throwing when it tries to create documentation for the code proper. I don't think it's worth trying to fix all of those as part of the initial issue but can file another and leave it as a TODO in the readthedocs.yaml file.
ETA: this new issue is #304

[robrap]

@feanil: I know you put in a lot of work to clean up warnings. How important do you think that is as a goal for maintainers of legacy repos? I also want to note that .readthedocs.yaml doesn't exist in the cookiecutter, and I wonder if it should. For new repos, it might be simpler to have docs fail on warnings, but I imagine that should match a config that is elsewhere so that the docs build in a repo (which doesn't use this yaml) will appropriately fail?

[rgraber]

FYI the build is now passing on Readthedocs so I'm going to close this ticket. I would suggest moving further discussions of fixing warnings to #304, even if discussion ends up being "we don't care."

[robrap]

[inform] I added a note on #304 about the corresponding Makefile change that is needed.