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

Lots of warnings now building the docs #7253

Closed
PaulWessel opened this issue Feb 19, 2023 · 9 comments · Fixed by #7889 or #7890
Closed

Lots of warnings now building the docs #7253

PaulWessel opened this issue Feb 19, 2023 · 9 comments · Fixed by #7889 or #7890
Labels
documentation Improve documentation

Comments

@PaulWessel
Copy link
Member

Maybe this is standard but recently switched to home-brew and after git pull etc and building docs I get an enormous list of warnings like this:

[559/559] Building HTML documentation...
/Users/pwessel/UH/RESEARCH/CVSPROJECTS/GMTdev/gmt-dev/rbuild/doc/rst/source/explain_-V.rst_:: WARNING: duplicate label -v, other instance in /Users/pwessel/UH/RESEARCH/CVSPROJECTS/GMTdev/gmt-dev/rbuild/doc/rst/source/basemap.rst
/Users/pwessel/UH/RESEARCH/CVSPROJECTS/GMTdev/gmt-dev/rbuild/doc/rst/source/explain_-V.rst_:: WARNING: duplicate label -v, other instance in /Users/pwessel/UH/RESEARCH/CVSPROJECTS/GMTdev/gmt-dev/rbuild/doc/rst/source/batch.rst
/Users/pwessel/UH/RESEARCH/CVSPROJECTS/GMTdev/gmt-dev/rbuild/doc/rst/source/explain_-I.rst_:: WARNING: duplicate label -i, other instance in /Users/pwessel/UH/RESEARCH/CVSPROJECTS/GMTdev/gmt-dev/rbuild/doc/rst/source/batch.rst
/Users/pwessel/UH/RESEARCH/CVSPROJECTS/GMTdev/gmt-dev/rbuild/doc/rst/source/explain_-R.rst_:: WARNING: duplicate label -r, other instance in /Users/p

Anything obvious to those who speak RST?
@PaulWessel PaulWessel added bug Something isn't working documentation Improve documentation labels Feb 19, 2023
@KristofKoch
Copy link
Contributor

I get those too and found that someone else had apparently the same problem. Maybe it is a lead worth following?

@PaulWessel
Copy link
Member Author

We put faith in @seisman or @maxrjones to figure this out at some point.

@joa-quim
Copy link
Member

Hmm, I only get these (and half come from non-committed branches

ninja docs_html
[557/557] Building HTML documentation...
C:\v\build\doc\rst\source\supplements\geodesy\earthtide.rst:94: ERROR: Unknown target name: "generate 1d array".
C:\v\build\doc\rst\source\supplements\potential\gmtflexure.rst:71: ERROR: Unknown target name: "generate 1d array".
C:\v\build\doc\rst\source\supplements\potential\talwani2d.rst:94: ERROR: Unknown target name: "generate 1d array".
source/explain_-R.rst_:6: WARNING: Duplicate explicit target name: "-r".
source/explain_-V.rst_:6: WARNING: Duplicate explicit target name: "-v".
C:\v\build\doc\rst\source\supplements\seis\shake.rst:8: ERROR: Undefined substitution referenced: "shake_purpose".
source/explain_-R.rst_:6: WARNING: Duplicate explicit target name: "-r".
source/explain_-V.rst_:6: WARNING: Duplicate explicit target name: "-v".
source/explain_-r.rst_:6: WARNING: Duplicate explicit target name: "-r".
C:\v\build\doc\rst\source\supplements\seis\vs30.rst:8: ERROR: Undefined substitution referenced: "vs30_purpose".
source/explain_-r.rst_:2: WARNING: duplicate label supplements/seis/vs30:the **-r** option, other instance in C:\v\build\doc\rst\source\supplements\seis\vs30.rst
C:\v\build\doc\rst\source\supplements\seis\shake.rst: WARNING: document isn't included in any toctree
C:\v\build\doc\rst\source\supplements\seis\vs30.rst: WARNING: document isn't included in any toctree
C:\v\build\doc\rst\source\cookbook\cpts.rst:105: WARNING: a suitable image for html builder not found: _images/GMT_App_M_1e.*

@joa-quim
Copy link
Member

Now I also get hundreds of them.

@joa-quim joa-quim removed the bug Something isn't working label Jul 23, 2023
@seisman
Copy link
Member

seisman commented Oct 9, 2023 •
edited
Loading

Sphinx makes all explicit targets available globally, thus all targets must be unique in the entire documentation. In our docs, we define targets like -V in one file and include it in many docs. That's why we see so many "duplicate label" warnings.

As far as I know, there is no option to suppress these warnings. So our only choice is to redirect all these warnings into a log file, and then use grep to filter out these useless warnings.

@seisman seisman mentioned this issue Oct 9, 2023
Merged
@PaulWessel
Copy link
Member Author

I agree, silly decision by Sphinx. The grepped log is a good suggestion

@anbj
Copy link
Contributor

anbj commented Oct 9, 2023

I can't understand that no one has posted a feature request regarding this with the sphinx folks.
Surely must be a nuisance for others as well.

appending __ to the target or something similar does not do anything either? (blind shot)

@seisman
Copy link
Member

seisman commented Oct 9, 2023

I can't understand that no one has posted a feature request regarding this with the sphinx folks.
Surely must be a nuisance for others as well.

There are already some complaints similar to our situation (e.g., sphinx-doc/sphinx#10202).

appending __ to the target or something similar does not do anything either? (blind shot)

I don't think it will work. The same target is still defined multiple times in the entire docs.

@seisman
Copy link
Member

seisman commented Oct 9, 2023

After filtering out the useless "duplicate label" warnings, here are the useful warnings, and some are critical:

/home/runner/work/gmt/gmt/build/doc/rst/_extensions/youtube/utils.py:9: RemovedInSphinx80Warning: The alias 'sphinx.util.status_iterator' is deprecated, use 'sphinx.util.display.status_iterator' instead. Check CHANGES for Sphinx API modifications.
  from sphinx.util import logging, status_iterator
/home/runner/work/gmt/gmt/build/doc/rst/source/basemap.rst:201: WARNING: Literal block expected; none found.
/home/runner/work/gmt/gmt/build/doc/rst/source/clear.rst:65: WARNING: duplicate label clear:optional arguments, other instance in /home/runner/work/gmt/gmt/build/doc/rst/source/clear.rst
/home/runner/work/gmt/gmt/build/doc/rst/source/colorbar.rst:207: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/home/runner/work/gmt/gmt/build/doc/rst/source/gmtselect.rst:206: WARNING: Definition list ends without a blank line; unexpected unindent.
/home/runner/work/gmt/gmt/build/doc/rst/source/explain_gshhg.rst_:4: WARNING: duplicate label gshhg-information, other instance in /home/runner/work/gmt/gmt/build/doc/rst/source/coast.rst
/home/runner/work/gmt/gmt/build/doc/rst/source/explain_gshhg.rst_:4: WARNING: duplicate label gshhg-information, other instance in /home/runner/work/gmt/gmt/build/doc/rst/source/gmtselect.rst
/home/runner/work/gmt/gmt/build/doc/rst/source/grdmath.rst:404: WARNING: Blank line required after table.
/home/runner/work/gmt/gmt/build/doc/rst/source/explain_gshhg.rst_:4: WARNING: duplicate label gshhg-information, other instance in /home/runner/work/gmt/gmt/build/doc/rst/source/grdlandmask.rst
/home/runner/work/gmt/gmt/build/doc/rst/source/grdpaste.rst:57: WARNING: Definition list ends without a blank line; unexpected unindent.
/home/runner/work/gmt/gmt/build/doc/rst/source/makecpt.rst:180: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/home/runner/work/gmt/gmt/build/doc/rst/source/explain_gshhg.rst_:4: WARNING: duplicate label gshhg-information, other instance in /home/runner/work/gmt/gmt/build/doc/rst/source/grdmath.rst
source/colorbar.rst:168: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/home/runner/work/gmt/gmt/build/doc/rst/source/supplements/geodesy/earthtide.rst:94: ERROR: Unknown target name: "generate 1d array".
/home/runner/work/gmt/gmt/build/doc/rst/source/supplements/potential/gmtflexure.rst:71: ERROR: Unknown target name: "generate 1d array".
/home/runner/work/gmt/gmt/build/doc/rst/source/supplements/potential/talwani2d.rst:94: ERROR: Unknown target name: "generate 1d array".
source/explain_-J.rst_:3: WARNING: Duplicate explicit target name: "-j".
source/explain_-J.rst_:3: WARNING: Duplicate explicit target name: "-j".
/home/runner/work/gmt/gmt/build/doc/rst/source/supplements/windbarbs/grdbarb.rst:167: CRITICAL: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/explain_grd_inout_short.rst_'.
/home/runner/work/gmt/gmt/build/doc/rst/source/supplements/windbarbs/grdbarb.rst:9: ERROR: Undefined substitution referenced: "grdbarb_purpose".
source/explain_-J.rst_:3: WARNING: Duplicate explicit target name: "-j".
/home/runner/work/gmt/gmt/build/doc/rst/source/tutorial/intro.rst:42: WARNING: unknown document: 'install'
/home/runner/work/gmt/gmt/build/doc/rst/source/tutorial/intro_jl.rst:29: WARNING: unknown document: 'install'

@seisman seisman reopened this Oct 9, 2023
@seisman seisman mentioned this issue Oct 9, 2023
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation Improve documentation
Projects
None yet
Milestone
No milestone
5 participants
@joa-quim @seisman @PaulWessel @anbj @KristofKoch