search

JuliaLang / julia

The Julia Programming Language
https://julialang.org/
MIT License
45.58k stars 5.47k forks source link

[doc]: unresolved path in stdlib/LinearAlgebra.md #44068

Open simeonschaub opened 2 years ago

simeonschaub commented 2 years ago

Building the docs currently emits the following two warnings:

   Installed Parsers ──── v2.2.0
   Installed Documenter ─ v0.27.12
Precompiling project...
  6 dependencies successfully precompiled in 9 seconds
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Warning: invalid local link: unresolved path in stdlib/LinearAlgebra.md
│   link.text =
│    1-element Vector{Any}:
│     Markdown.Code("", "\\")
│   link.url = "math.html#Base.:\\-Tuple{Any, Any}"
└ @ Documenter.Writers.HTMLWriter ~/Documents/Julia/julia/doc/deps/packages/Documenter/Nu7Lp/src/Writers/HTMLWriter.jl:2078
┌ Warning: invalid local link: unresolved path in stdlib/LinearAlgebra.md
│   link.text =
│    1-element Vector{Any}:
│     Markdown.Code("", "rdiv!")
│   link.url = "../stdlib/LinearAlgebra.html#LinearAlgebra.rdiv!"
└ @ Documenter.Writers.HTMLWriter ~/Documents/Julia/julia/doc/deps/packages/Documenter/Nu7Lp/src/Writers/HTMLWriter.jl:2078
Build finished. The HTML pages are in _build/html.
make: Leaving directory '/home/simeon/Documents/Julia/julia/doc'

Seems to have been caused by #43632.

inkydragon commented 2 years ago

But the generated links are all valid.

  1. math/#Base.:\-Tuple{Any, Any}
  2. LinearAlgebra/#LinearAlgebra.rdiv!
dkarrasch commented 1 year ago

Is this still relevant?

inkydragon commented 1 year ago

Maybe yes.

Julia Version 1.8.2 Commit 36034abf260 (2022-09-29 15:21 UTC)

https://buildkite.com/julialang/julia-master/builds/17914#01844664-8905-4be9-a811-6922a08bc0ad/608-641

┌ Warning: invalid local link: unresolved path in manual/command-line-interface.md
│   link.text =
│    1-element Vector{Any}:
│     "The Julia REPL"
│   link.url = "and not when `julia` is *e.g.* run on a script"
└ @ Documenter.Writers.HTMLWriter /cache/build/default-amdci5-7/julialang/julia-master/doc/deps/packages/Documenter/yf96B/src/Writers/HTMLWriter.jl:2081
┌ Warning: invalid local link: unresolved path in base/numbers.md
│   link.text =
│    1-element Vector{Any}:
│     Markdown.Code("", "typemax")
│   link.url = "../base/#Base.typemax"
└ @ Documenter.Writers.HTMLWriter /cache/build/default-amdci5-7/julialang/julia-master/doc/deps/packages/Documenter/yf96B/src/Writers/HTMLWriter.jl:2081
┌ Warning: invalid local link: unresolved path in base/numbers.md
│   link.text =
│    1-element Vector{Any}:
│     Markdown.Code("", "missing")
│   link.url = "../base/#Base.missing"
└ @ Documenter.Writers.HTMLWriter /cache/build/default-amdci5-7/julialang/julia-master/doc/deps/packages/Documenter/yf96B/src/Writers/HTMLWriter.jl:2081
┌ Warning: invalid local link: unresolved path in stdlib/LinearAlgebra.md
│   link.text =
│    1-element Vector{Any}:
│     Markdown.Code("", "rdiv!")
│   link.url = "../../stdlib/LinearAlgebra/#LinearAlgebra.rdiv!"
└ @ Documenter.Writers.HTMLWriter /cache/build/default-amdci5-7/julialang/julia-master/doc/deps/packages/Documenter/yf96B/src/Writers/HTMLWriter.jl:2081
vtjnash commented 1 year ago

Here is an example of the error indicated: image

Where that link tries to open https://docs.julialang.org/en/v1/stdlib/stdlib/LinearAlgebra/#LinearAlgebra.rdiv! (note the duplicate stdlib/)

vtjnash commented 1 year ago

Here is another similar instance of the bug: image

This is the opposite of those reported above. Here we see typemax in those 2 places (generated from exactly the same source) point to 2 different places, one of them broken, and neither is mentioned in the warning.

vtjnash commented 1 year ago

In the rdiv case, note that the text of the docstring is getting duplicated to 2 places, including https://docs.julialang.org/en/v1.10-dev/base/math/#Base.:/

130 vtjnash@arctic4:/data/vtjnash/julia1/doc$ grep -RI 'Matrix right-div' _build/html/en/*/ ../base/ ../stdlib/*/src
_build/html/en/base/math.html:2.25</code></pre></div><a class="docs-sourcelink" target="_blank" href="https://github.com/JuliaLang/julia/blob/6976bacd66e606865f656312bf6d991f3a6e4507/base/docs/basedocs.jl#L2717-L2734">source</a></section><section><div><pre><code class="language-julia hljs">A / B</code></pre><p>Matrix right-division: <code>A / B</code> is equivalent to <code>(B&#39; \ A&#39;)&#39;</code> where <a href="math.html#Base.:\\-Tuple{Any, Any}"><code>\</code></a> is the left-division operator. For square matrices, the result <code>X</code> is such that <code>A == X*B</code>.</p><p>See also: <a href="../stdlib/LinearAlgebra.html#LinearAlgebra.rdiv!"><code>rdiv!</code></a>.</p><p><strong>Examples</strong></p><pre><code class="language-julia-repl hljs">julia&gt; A = Float64[1 4 5; 3 9 2]; B = Float64[1 4 2; 3 4 2; 8 7 1];
_build/html/en/stdlib/LinearAlgebra.html:true</code></pre></div><a class="docs-sourcelink" target="_blank" href="https://github.com/JuliaLang/julia/blob/6976bacd66e606865f656312bf6d991f3a6e4507/stdlib/LinearAlgebra/src/generic.jl#L1070-L1100">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Base.:/-Tuple{AbstractVecOrMat, AbstractVecOrMat}" href="#Base.:/-Tuple{AbstractVecOrMat, AbstractVecOrMat}"><code>Base.:/</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">A / B</code></pre><p>Matrix right-division: <code>A / B</code> is equivalent to <code>(B&#39; \ A&#39;)&#39;</code> where <a href="stdlib/math.html#Base.:\\-Tuple{Any, Any}"><code>\</code></a> is the left-division operator. For square matrices, the result <code>X</code> is such that <code>A == X*B</code>.</p><p>See also: <a href="stdlib/LinearAlgebra.html#LinearAlgebra.rdiv!"><code>rdiv!</code></a>.</p><p><strong>Examples</strong></p><pre><code class="language-julia-repl hljs">julia&gt; A = Float64[1 4 5; 3 9 2]; B = Float64[1 4 2; 3 4 2; 8 7 1];
../stdlib/LinearAlgebra/src/generic.jl:Matrix right-division: `A / B` is equivalent to `(B' \\ A')'` where [`\\`](@ref) is the left-division operator.
vtjnash commented 1 year ago

Filed an upstream bug: https://github.com/JuliaDocs/Documenter.jl/issues/2042

though the first one is actually a legitimate missing (@ref) in the source

diff --git a/doc/src/manual/command-line-interface.md b/doc/src/manual/command-line-interface.md
index 54c56a354c..ac6b79c34b 100644
--- a/doc/src/manual/command-line-interface.md
+++ b/doc/src/manual/command-line-interface.md
@@ -69,7 +69,7 @@ Note that although you should have a `~/.julia` directory once you've run Julia
 first time, you may need to create the `~/.julia/config` folder and the
 `~/.julia/config/startup.jl` file if you use it.

-To have startup code run only in [The Julia REPL] (and not when `julia` is *e.g.* run
+To have startup code run only in [The Julia REPL](@ref) (and not when `julia` is *e.g.* run
 on a script), use [`atreplinit`](@ref) in `startup.jl`:

 ```julia
vtjnash commented 1 year ago

Tangentially related, but I will just mention here for now, that all of the stdlib source links are not correct. For example: image tries to go to: https://github.com/JuliaLang/julia/blob/1270b34b64f367a6c5da5576b85c13cc0c26ffea/usr/share/julia/stdlib/v1.10/FileWatching/src/pidfile.jl#L287-L291