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.

Sign up for GitHub

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

Jump to bottom

Sphinx 9 deprecations #37887

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Sphinx 9 deprecations #37887

wants to merge 5 commits into from

Conversation

jclarkeSTFC
Copy link
Contributor

At the time of writing we are using Sphinx 8, but generating the docs gives warnings about the use of strings to represent file paths not being allowed in Sphinx 9.

  • Replaced strings representing file paths with pathlib.Path objects
  • Replaces tags.tags with tags

Fixes #37804.

To test:

  • Build docs, no warnings
  • Should be no warnings in the doc test build either (see Fix sphinx file path deprecation warning #37804 for the message you get when the warnings are present)
  • Check that the docs look correct and the links work
  • Check release note generation (I changed amalgamate.py)

This does not require release notes because it has no effect on the user.

Reviewer

Please comment on the points listed below (full description).
Your comments will be used as part of the gatekeeper process, so please comment clearly on what you have checked during your review. If changes are made to the PR during the review process then your final comment will be the most important for gatekeepers. In this comment you should make it clear why any earlier review is still valid, or confirm that all requested changes have been addressed.

Code Review

  • Is the code of an acceptable quality?
  • Does the code conform to the coding standards?
  • Are the unit tests small and test the class in isolation?
  • If there is GUI work does it follow the GUI standards?
  • If there are changes in the release notes then do they describe the changes appropriately?
  • Do the release notes conform to the release notes guide?

Functional Tests

  • Do changes function as described? Add comments below that describe the tests performed?
  • Do the changes handle unexpected situations, e.g. bad input?
  • Has the relevant (user and developer) documentation been added/updated?

Does everything look good? Mark the review as Approve. A member of @mantidproject/gatekeepers will take care of it.

Gatekeeper

If you need to request changes to a PR then please add a comment and set the review status to "Request changes". This will stop the PR from showing up in the list for other gatekeepers.

@jclarkeSTFC jclarkeSTFC added Documentation Issues and pull requests related to documentation Maintenance Unassigned issues to be addressed in the next maintenance period. ISIS Team: Core Issue and pull requests managed by the Core subteam at ISIS labels Aug 28, 2024
@jclarkeSTFC jclarkeSTFC added this to the Release 6.12 milestone Aug 28, 2024
@sf1919
Copy link
Contributor

sf1919 commented Aug 29, 2024

Given you are putting this in now is it likely to be merged into main before code freeze? Thats still about 2 weeks away.

@jclarkeSTFC
Copy link
Contributor Author

Given you are putting this in now is it likely to be merged into main before code freeze? Thats still about 2 weeks away.

Yes should be done by then

@sf1919
Copy link
Contributor

sf1919 commented Aug 29, 2024

Maybe change the milestone?

@jclarkeSTFC jclarkeSTFC force-pushed the 37804_sphinx_9_deprecations branch 2 times, most recently from 08c4d8d to 1a86be6 Compare September 10, 2024 09:28
@jhaigh0 jhaigh0 self-assigned this Sep 12, 2024
@jclarkeSTFC jclarkeSTFC force-pushed the 37804_sphinx_9_deprecations branch 2 times, most recently from db5b040 to 6fc75eb Compare September 16, 2024 15:21
@jclarkeSTFC jclarkeSTFC marked this pull request as ready for review September 17, 2024 08:03
jhaigh0
jhaigh0 reviewed Sep 17, 2024
View reviewed changes
Copy link
Contributor

@jhaigh0 jhaigh0 left a comment

Choose a reason for hiding this comment

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

Unfortunately when viewing the index pages for, Algorithms, Concepts, etc. I'm not seeting any css
image

I did get a failure when building the docs 43>C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Microsoft\VC\v160\Microsoft.CppCommon.targets(241,5): error MSB8066: Custom build for 'C:\Users\bya67386\work\mantid\build\CMakeFiles\a174ffb83d39874e18c7afe905d635e0\docs-html.rule;C:\Users\bya67386\work\mantid\docs\CMakeLists.txt' exited with code 1.
And some warnings (although not the deprecation warnings.) but this might be to do with my weird build problems.

@jclarkeSTFC
Use pathlib.Path to represent file paths in Sphinx
1271dd4 
From Sphinx 9 onwards it will not be possible to use a string to
represent a file path, so I've replaced all such occurrences with
pathlib.Path.
@jclarkeSTFC
Remove use of deprecated tags.tags
6821151 
From Sphinx 9 onwards tags.tags will be removed.
@jclarkeSTFC
Revert uses of relative_to() to os.path.relpath
c35f82c 
pathlib.Path.relative_to() apparently will not traverse the file
hierarchy both up then down again, so if you want to find the
relative path between two locations in that case you need
os.path.relpath().
@jclarkeSTFC
Fix name in categories directive
80da950 
The name can contain backslashes that need converting to
posix format before going into the subsequent code. Otherwise
the backslashes will break the documentation folder structure.
@jclarkeSTFC jclarkeSTFC marked this pull request as draft October 2, 2024 11:02
@jclarkeSTFC
Use PurePosixPath instead of Path where appropriate
9261945 
Sphinx wants us to use pathlib.Path to represent filesystem paths,
but on Windows Sphinx can't handle the backslashes that come
out of Path. Hence if we use PurePosixPath we can make sure we
get forward slashes.
@jclarkeSTFC jclarkeSTFC marked this pull request as ready for review October 3, 2024 07:19
@jclarkeSTFC
Copy link
Contributor Author

Unfortunately when viewing the index pages for, Algorithms, Concepts, etc. I'm not seeting any css image

I did get a failure when building the docs 43>C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Microsoft\VC\v160\Microsoft.CppCommon.targets(241,5): error MSB8066: Custom build for 'C:\Users\bya67386\work\mantid\build\CMakeFiles\a174ffb83d39874e18c7afe905d635e0\docs-html.rule;C:\Users\bya67386\work\mantid\docs\CMakeLists.txt' exited with code 1. And some warnings (although not the deprecation warnings.) but this might be to do with my weird build problems.

This should be fixed now

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jhaigh0 jhaigh0 jhaigh0 left review comments

At least 1 approving review is required to merge this pull request.

Assignees

@jhaigh0 jhaigh0

Labels
Documentation Issues and pull requests related to documentation ISIS Team: Core Issue and pull requests managed by the Core subteam at ISIS Maintenance Unassigned issues to be addressed in the next maintenance period.
Projects
None yet
Milestone
Release 6.12
Development

Successfully merging this pull request may close these issues.

Fix sphinx file path deprecation warning
3 participants
@jclarkeSTFC @sf1919 @jhaigh0