Comments (6)
The suggested workaround to use header @id
's is not working either.
[ Info: CrossReferences: building cross-references.
┌ Error: Cannot resolve @ref for md"[Applying Multiple Operations per Manipulation](@ref multi_op_manipulations)" in src\man\basics.md.
│ - No docstring found in doc for binding `Main.multi_op_manipulations`.
└ @ Documenter C:\Users\nboyer.AIP\.julia\packages\Documenter\CJeWX\src\utilities\utilities.jl:44
┌ Error: Cannot resolve @ref for md"[Broadcasting Operation Pairs](@ref broadcasting_operation_pairs)" in src\man\basics.md.
│ - No docstring found in doc for binding `Main.broadcasting_operation_pairs`.
└ @ Documenter C:\Users\nboyer.AIP\.julia\packages\Documenter\CJeWX\src\utilities\utilities.jl:44
Line 1675:
See the later sections [Applying Multiple Operations per Manipulation](@ref multi_op_manipulations)
and [Broadcasting Operation Pairs](@ref broadcasting_operation_pairs) for more information.
Line 2514:
### [Applying Multiple Operations per Manipulation](@id multi_op_manipulations)
Line 2649:
### [Broadcasting Operation Pairs](@id broadcasting_operation_pairs)
from documenter.jl.
Is it because they are referred to above where they are defined?
from documenter.jl.
I just tested with
[link](@ref an_index_of_docstrings)
[`link`](@ref an_index_of_docstrings)
### [An index of docstrings](@id an_index_of_docstrings)
and so does
[another link](@ref "Multiple uses of the same symbol")
[Multiple uses of the same symbol](@ref)
### Multiple uses of the same symbol
actually. So everything should work.. It would be good if we could reduce the issue down to an MWE.
from documenter.jl.
Well it's not minimum yet, but I ran into some strange behavior. If I delete everything but the headers and references, then the cross-references build okay. Somewhere in between it fails. I am testing by running julia --project make.jl
from the docs
folder.
Here is my smaller failing example.
https://github.com/nathanrboyer/DataFrames.jl/tree/doc_MWE
make.jl
using Documenter
using DataFrames
makedocs(
modules = [DataFrames],
doctest = false,
clean = true,
sitename = "DataFrames.jl",
format = Documenter.HTML(
canonical = "https://juliadata.github.io/DataFrames.jl/stable/",
assets = ["assets/favicon.ico"],
edit_link = "main",
size_threshold_ignore = ["man/basics.md", "lib/functions.md"],
),
pages = Any[
"Introduction" => "index.md",
"First Steps with DataFrames.jl" => "man/basics.md",
],
)
index.md
# DataFrames.jl
## Package Manual
```@contents
Pages = ["man/basics.md"]
Depth = 2
```
basics.md
basics.md
basics.md
Edits
As uploaded, the cross-references fail:
┌ Error: Cannot resolve @ref for md"[Applying Multiple Operations per Manipulation](@ref)" in src\man\basics.md.
│ - No docstring found in doc for binding `Base.-`.
└ @ Documenter C:\Users\nboyer.AIP\.julia\packages\Documenter\CJeWX\src\utilities\utilities.jl:44
┌ Error: Cannot resolve @ref for md"[Broadcasting Operation Pairs](@ref)" in src\man\basics.md.
│ - No docstring found in doc for binding `Base.-`.
If I delete from line 9 (just after the references) to line to line 843 (just before the definitions), then the cross-reference error disappears.
# First Steps with DataFrames.jl
## Manipulation Functions
*The manipulation functions also have methods for applying multiple operations.
See the later sections [Applying Multiple Operations per Manipulation](@ref)
and [Broadcasting Operation Pairs](@ref) for more information.*
### Applying Multiple Operations per Manipulation
### Broadcasting Operation Pairs
.
.
.
$ julia --project make.jl
Activating project at `C:\Users\nboyer.AIP\Documents\Julia\Forks\DataFrames\docs`
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: skipped.
[ 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.
┌ Error: Generated HTML over size_threshold limit: lib\functions.md
│ Generated file size: 454.43 (KiB)
│ size_threshold_warn: 100.0 (KiB)
│ size_threshold: 200.0 (KiB)
│ HTML file: lib\functions/index.html
└ @ Documenter.HTMLWriter C:\Users\nboyer.AIP\.julia\packages\Documenter\CJeWX\src\html\HTMLWriter.jl:1821
ERROR: LoadError: HTMLSizeThresholdError: Some generated HTML files are above size_threshold.
See logged errors for details.
Alternatively, if I keep the previous lines, and instead delete from line 848 to the end (the "Approach Comparison" section), then the cross-reference error also disappears, and I get the same output as above.
This leaves me somewhat stumped because there are at least two distinct paths to remove the error, neither of which appear to have anything to do with the headers or references themselves.
from documenter.jl.
I was able to trim the basics.md
file down to 17 lines. It seems to have something to do with code blocks and/or admonitions as well as the order in which they appear.
CrossReferences Fail:
Original
# Header 1
## Header 2
Reference [Header 3](@ref).
!!! Note
```julia
"hello"
```
### Header 3
```julia
"hello"
```
CrossReferences Pass:
Remove code block.
# Header 1
## Header 2
Reference [Header 3](@ref).
!!! Note
```julia
"hello"
```
### Header 3
hello
CrossReferences Pass:
Remove code block in note.
# Header 1
## Header 2
Reference [Header 3](@ref).
!!! Note
hello
### Header 3
```julia
"hello"
```
CrossReferences Pass:
Remove note.
# Header 1
## Header 2
Reference [Header 3](@ref).
```julia
"hello"
```
### Header 3
```julia
"hello"
```
CrossReferences Pass:
Move note to bottom.
# Header 1
## Header 2
Reference [Header 3](@ref).
### Header 3
```julia
"hello"
```
!!! Note
```julia
"hello"
```
CrossReferences Pass:
Move code block to top.
# Header 1
## Header 2
Reference [Header 3](@ref).
!!! Note
```julia
"hello"
```
```julia
"hello"
```
### Header 3
CrossReferences Pass:
Reference Header 2 instead of 3.
# Header 1
## Header 2
Reference [Header 2](@ref).
!!! Note
```julia
"hello"
```
### Header 3
```julia
"hello"
```
Hopefully you can make something of this. I don't think I can take it any further myself.
from documenter.jl.
"Note" needs to be lowercase. It rendered fine in VSCode, so I didn't notice. Not sure what that has to do with the thrown cross-reference error, but at least that fixed it.
from documenter.jl.
Related Issues (20)
- Alternative admonition syntax?
- Support for external parsers like CommonMark HOT 2
- Profiling docs build times HOT 3
- Not Matching Versions for Subpackage Version Tags HOT 1
- docstrings in extensions HOT 1
- Add a note to contributor docs about how to format code
- Add `make` command to run prettier
- Deserialization in Julia code blocks can throw an error. HOT 2
- proposal for rendering images when last value from @example blocks HOT 5
- Generated files with Documenter.jl and julia-docdeploy have random characters included in their name, not rendering correctly HOT 4
- Feature request: Cross module links HOT 2
- (Perhaps) Incorrectly interpreting square brackets in docstrings as links HOT 3
- Undesirable `Main.var"Main"` qualification of new modules HOT 2
- html field type not implemented HOT 1
- Can we make search modify the URL HOT 4
- Erroneous Errors with `checkdocs`
- Feature request: ANSI color output in reference documentation HOT 6
- Option to Disable collapse/expand HOT 2
- How to use `@repl` and `@example` in docstring?
- Linkcheck failing because of user agent used by Documenter
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from documenter.jl.