.github/workflows/doc-build.yml: Fix generation of CHANGES.html #35808
Conversation
…lt documentation around running doc-clean
mkoeppe
force-pushed
the
ci_docbuild_fix_changes
branch
from
202fd62 to
9905d4e
Compare
| mv /sage/local/share/doc/sage/html/en/.git /sage/.git-doc | ||
| make doc-clean doc-uninstall sagelib-clean && git clean -fx src/sage | ||
| mkdir -p /sage/local/share/doc/sage/html/en/ && mv /sage/.git-doc /sage/local/share/doc/sage/html/en/ | ||
| ./config.status && make doc-html |
There was a problem hiding this comment.
Move .git-doc to .git-doc? No .git?
Where is the code to generate CHANGES.html? No idea how this works.
There was a problem hiding this comment.
Thanks, fixed now.
CHANGES.html is generated in the "Copy docs" step
There was a problem hiding this comment.
Are you aware that L53 is very similar to L100 in the "Copy docs" step. This seems to be a mistake to me...
There was a problem hiding this comment.
What is the net effect of L83 and L85. It is moving .git directory to and from .gitdoc. Why?
There was a problem hiding this comment.
In particular, why mkdir -p /sage/local/share/doc/sage/html/en/. The directory already exists. Why create it again?
There was a problem hiding this comment.
I'm moving the .git directory away and back to protect it from make doc-uninstall
|
Most of the files in |
|
I think they are all caused by functions whose default arguments display a hex address |
|
I don't know if wiping out sage version from the sidebar is a good idea... If I would change it at all and if possible, then I would augment the version number with the PR number, like |
|
By second thought, I would not change the version number at all because checking if the version number appear correct in the documentation is itself a part of the purpose of the documentation preview. |
Yeah. I see. |
|
And how about providing diff separately for each changed html, instead of one giant diff If there is a free API service that show git diff nicely, then we may use that... |
Without making the version number equal between both versions, every single file would show up in the diff |
|
Both should show the same latest beta version. No? But I guess there could be a mismatch, for example, for some short time before the latest beta appears in the docker image, or when the branch of a PR is not rebased onto the latest beta. Is your making-version-number-equal a provision for these situations? |
|
Yes, that's right, it's intended for these situations. I don't think they are uncommon. |
|
I agree that they are common. But if the author recognizes the version mismatch, then he/she can just upload the branch merged with the latest beta, which I think is, anyway, a good thing to do. Also this is just optional. On the other hand, we frequently create links to the doc built for a PR, then it is good that the doc is accompanied with the right beta version number. I am not sure about this matter though. I would not insist for now. |
|
I'll change it so that the old copy gets updated with the version number of the PR branch. |
|
Thanks. It seems a good compromise. |
|
This is of course a wishlist item.
There is https://diffy.org/. But it seems not work with a url. |
|
Documentation preview for this PR (built with commit ebde730; changes) is ready! 🎉 |
kwankyu
added
s: positive review
p: critical / 2
c: documentation
and removed
s: needs review
c: documentation
labels
|
Thanks for the review! |
It wouldn't be too hard to use https://diff2html.xyz/ |
📚 Description
This new feature from #35652 was supposed to show the changed HTML files,
but a last minute change there destroyed it.
Here we fix it.
📝 Checklist
⌛ Dependencies