Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update RTD configuration #525

Merged
merged 1 commit into from
Mar 5, 2024
Merged

Update RTD configuration #525

merged 1 commit into from
Mar 5, 2024

Conversation

akatsoulas
Copy link
Collaborator

No description provided.

docs/conf.py Outdated
@@ -185,12 +186,12 @@
# -- Options for LaTeX output --------------------------------------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you do a sphinx-quickstart in a new project, it produces a very very very small conf.py file that doesn't have a lot of these options. I did a pass on some of my libraries to reduce the conf.py file. Maybe we do a pass on reducing the conf.py file in this PR?

For example, here's the Markus one: https://github.com/willkg/markus/blob/main/docs/conf.py

@@ -0,0 +1,3 @@
sphinx==7.2.6
sphinx_rtd_theme==2.0.0
readthedocs-sphinx-search==0.3.2
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we have some signal for when the docs fail to build, we could not pin these and then we wouldn't have to update them periodically.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created a group to receive notifications for when the builds fail. I will remove the pinning.

Copy link
Member

@willkg willkg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks fine to me, but I'd probably take a pass at reducing conf.py, too.

@akatsoulas
Copy link
Collaborator Author

@willkg could you maybe have another pass at this? conf.py has been reduced and pinning has been removed from the doc requirements file.

Copy link
Member

@willkg willkg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs don't build with these changes. If I install requirements from requirements/requirements-dev.txt, then they build. There are some warnings in the output.


import mozilla_django_oidc # noqa
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These won't work unless docs/requirements.txt include all the dev requirements (e.g. django). If I create a fresh virtual environment, install docs/requirements.txt, and then do make docs, I get this:

$ make docs
rm -rf docs/source
sphinx-apidoc -o docs/source/ mozilla_django_oidc
make -C docs clean
make[1]: Entering directory '/home/willkg/mozilla/mozilla-django-oidc/docs'
rm -rf _build/*
make[1]: Leaving directory '/home/willkg/mozilla/mozilla-django-oidc/docs'
make -C docs html
make[1]: Entering directory '/home/willkg/mozilla/mozilla-django-oidc/docs'
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v7.2.6

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/willkg/.pyenv/versions/3.10.12/lib/python3.10/site-packages/sphinx/config.py", line 358, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/willkg/mozilla/mozilla-django-oidc/docs/conf.py", line 20, in <module>
    import django  # noqa
ModuleNotFoundError: No module named 'django'

make[1]: *** [Makefile:53: html] Error 2
make[1]: Leaving directory '/home/willkg/mozilla/mozilla-django-oidc/docs'
make: *** [Makefile:38: docs] Error 2

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apologies for the back n forth here. I neglected to destroy my virtual environment which already had the packages. With the update make docs build without any errors for me. Hopefully one more pass :) ?

* fix docstring indentation
Copy link
Member

@willkg willkg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! No worries about the back-and-forth. :)

@akatsoulas akatsoulas merged commit dab7ed0 into mozilla:main Mar 5, 2024
23 checks passed
@akatsoulas akatsoulas deleted the rtd-conf branch March 5, 2024 17:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants