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

Upgrading sphinx to bipass logging problems #551

Merged
merged 8 commits into from
Jan 29, 2022

Conversation

john-science
Copy link
Member

@john-science john-science commented Jan 27, 2022

Description

In an effort to reduce the strain of people trying to create their own ARMI-adjacent docs, this PR upgrades the version of Sphinx we are using from 2.2.0 to 4.4.0. It also implements some important future-proofing against Python's continuous changes to the standard library method logging.Logger.log(). These changes together allow us to remove a bunch of calls to logging.setLoggerClass(), that were causing people trouble.

As part of my testing, I had GitHub Actions build these docs in Python 3.7, 3.8, and 3.9. And I verified that my changes to runLog.py and the docs dependencies work in all versions.

NOTE: Please do not Merge this PR!
NOTE: Please let John Merge this PR!
NOTE: John needs time to update downstream build systems before this PR is Merged!


Checklist

  • Tests have been added/updated to verify that the new or changed code works.
  • Docstrings were included and updated as necessary
  • The code is understandable and maintainable to people beyond the author
  • There is no commented out code in this PR.

If user exposed functionality was added/changed:

  • Documentation added/updated in the doc folder.
  • New or updated dependencies have been added to setup.py.

@john-science john-science added documentation Improvements or additions to documentation enhancement New feature or request labels Jan 27, 2022
@john-science john-science linked an issue Jan 27, 2022 that may be closed by this pull request
@john-science
Copy link
Member Author

@jakehader @drewejohnson This PR is in reference to Issue #518

@john-science
Copy link
Member Author

@ntouran There are some minor visual differences in the resultant docs, that I could see. Hopefully I didn't miss anything. We don't really have an SOP for when we make massive changes to the docs, to make sure everyone still likes the way they look. Hmm.

I had to exactly pin the versions of these three libraries in order for the built docs to look right:

  • sphinx-gallery==0.9.0
  • sphinx-rtd-theme==0.5.2
  • sphinxcontrib-apidoc==0.3.0

@john-science john-science changed the title Upgrade sphinx Upgrading sphinx to bipass logging problems Jan 27, 2022
Copy link
Member

@ntouran ntouran left a comment

Choose a reason for hiding this comment

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

approved with one simple comment

doc/requirements-docs.txt Show resolved Hide resolved
@john-science john-science merged commit 3f0e637 into terrapower:master Jan 29, 2022
@john-science john-science deleted the upgrade_sphinx branch January 29, 2022 09:03
scottyak pushed a commit to scottyak/armi that referenced this pull request Oct 27, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

ARMI Application Sphinx Build Error with ARMI Logger
2 participants