Closed markcmiller86 closed 1 year ago
biagas
commented
1 year ago Very strange, I don't see the warnings on a branch off develop that is about a week behind, but I do see it on a clean up-to-date checkout of develop. I tried comparing source between the two and don't see a difference that would cause the warnings.
markcmiller86
commented
1 year ago So, I do see when I do a sphinx-build on my macOS system. I am runnin 2.2.1 installed with VisIt's python install for 3.3.0.
That said, the messages cut-n-pasted in this ticket were actually grabbed from the build logs on ReadTheDocs itself.
biagas
commented
1 year ago Just looking at the warning regarding 'Acknowledgements', I found several files that have that as a header, is that the problem?
JustinPrivitera
commented
1 year ago JustinPrivitera
commented
1 year ago This is probably my fault; I wanted automatic label generation when I was doing the X Ray Image Query docs. I really really like automatic label generation. If we decide to undo my change to conf.py then that will require some reworking of the color tables docs and x ray query docs. I am happy to make those changes if that fixes all these warnings. I wonder if there is a way to fix the warnings and keep automatic label generation?
markcmiller86
commented
1 year ago @JustinPrivitera lemme take a quick look at local gen after removing that and see what we see. I suspect it is related.
For some reason, I recall sphinx community guidance to be to NOT use automatic label generation. Reason being, you can't go back and change section headings without breaking references. When you do anchors manually, you can change section headings without breaking references.
markcmiller86
commented
1 year ago Indeed, after removing the extension, the generation produces no duplicate label warnings and instead generates a ton of undefined label warnings in XRayImageQuery.rst...which is what we were expecting.
JustinPrivitera
commented
1 year ago Ok - I can fix the x ray image query docs (and maybe color table docs?). I assume we are removing the extension?
markcmiller86
commented
1 year ago I also get two warnings of undefined labels in Color_tables.rst
markcmiller86
commented
1 year ago I assume we are removing the extension?
That is my recommendation. Yeah, its a bit of a pain to ref sections that haven't had anchors applied to them already.
I'd also like to see if we can cause RTD build to fail on warnings so we'd catch it in our CI sooner.
JustinPrivitera
commented
1 year ago Ok. I can remove the extension and fix those two pages of documentation all at once. 👍
markcmiller86
commented
1 year ago Ok, great. When you do, can you please also add a new line, fail_on_warning: true at line 11 of .readthedocs.yaml as below for the sphinx block?
This will have the effect of failing ReadTheDocs builds when we are generating warnings. It should look something like what you see here.
markcmiller86
commented
1 year ago For some reason, I recall sphinx community guidance to be to NOT use automatic label generation.
FYI...https://docs.openedx.org/en/latest/documentors/decisions/0004-no-auto-section-label.html
markcmiller86
commented
1 year ago For some reason, I recall sphinx community guidance to be to NOT use automatic label generation.
FYI...https://docs.openedx.org/en/latest/documentors/decisions/0004-no-auto-section-label.html
As I think about this, the problem is that the auto-label creation is done essentially during sphinx-build and because of that, the labels don't persist across builds and because of that, they are apt to change as the content upon which they are based changes.
What would be a much better solution is a tool that would auto-inject labels into existing .rst files based upon content there. Such auto-generated lables would be generated essentially once and persist across builds and then even when section headings upon which they were originally based change, the labels themselves would not.
Come to think of it, we could write a script (or sphinx extension) that would do just that.
JustinPrivitera
commented
1 year ago Where can I go to actually see the warnings that building the docs generates for my branch?
biagas
commented
1 year ago On the PR page under the check, click on the Read the Docs 'Details' link. Then click on the 'View raw' link near the upper right corner.
We're getting a slew of
duplicate labelwarnings fromsphinx-build...