Comments (28)
Sure, no problem :) Thanks for providing this package, I am looking forward to new docs with nicer references (and might let you know once I have finished that).
from documentercitations.jl.
Alright, I looked into this, and the problem was that we were storing the Anchors
for the bibliographic references in doc.internal.headers
.
However, the internals of Documenter
rightfully assume that any Anchor.object
in doc.internal.headers
is an instance of MarkdownAST.Heading
, which has a level
attribute. In our case, Anchor.object
is an instance of Bibliography.Entry
.
The correct thing to do here is for DocumenterCitations
to maintain its own AnchorMap
for bibliographic references, which doesn't interact with any table of contents.
Fixed in #42
from documentercitations.jl.
You have to have one (or at least one, with caveats) canonical bibliography. By definition, that's where all citation links go.
Is "Scenario 3" identical to "Scenario 1" except for removing Canonical=false
?
Scenarios 2 seems unrelated. I don't think HTML
is exported in Documenter
. I have using Documenter
and then Documenter.HMTL(…)
in make.jl.
I'm not really sure what's going on in Scenario 3. It could be some weird interaction with the Markdown parser, similar to #14?
from documentercitations.jl.
Just for fun, try removing the colon from your citation keys
from documentercitations.jl.
Removed the colon already, all 3 scenarios are the same then.
Yes 3 is just 1 without Canonical=false.
from documentercitations.jl.
Ah yes I missed the caveat that a canonical reference list has to exist and added such a page (just covering the canonical one). Then I still get (concistently) The error from 3 now also in 1.
from documentercitations.jl.
Havin only one @bibliography
in references.md
(and that not even yet entered into the menu) like
# Literature
This is all literature mentioned / referenced in the `Manopt.jl` documenation.
Usually you will find a small reference section at the end of every documentation page that contains references.
```@bibliography
```
still yields
ERROR: LoadError: MethodError: no method matching header_level(::BibInternal.Entry)
Closest candidates are:
header_level(::Markdown.Header{N}) where N
@ Documenter ~/.julia/packages/Documenter/bYYzK/src/Utilities/Utilities.jl:380
Stacktrace:
[1] populate!(contents::Documenter.Documents.ContentsNode, document::Documenter.Documents.Document)
@ Documenter.Documents ~/.julia/packages/Documenter/bYYzK/src/Documents.jl:451
[2] populate!(document::Documenter.Documents.Document)
@ Documenter.Documents ~/.julia/packages/Documenter/bYYzK/src/Documents.jl:413
[3] runner(#unused#::Type{Documenter.Builder.Populate}, doc::Documenter.Documents.Document)
@ Documenter.Builder ~/.julia/packages/Documenter/bYYzK/src/Builder.jl:247
[4] dispatch(#unused#::Type{Documenter.Builder.DocumentPipeline}, x::Documenter.Documents.Document)
@ Documenter.Utilities.Selectors ~/.julia/packages/Documenter/bYYzK/src/Utilities/Selectors.jl:170
[5] #2
@ ~/.julia/packages/Documenter/bYYzK/src/Documenter.jl:273 [inlined]
[6] cd(f::Documenter.var"#2#3"{Documenter.Documents.Document}, dir::String)
@ Base.Filesystem ./file.jl:112
[7] makedocs(components::CitationBibliography; debug::Bool, format::Documenter.Writers.HTMLWriter.HTML, kwargs::Base.Pairs{Symbol, Any, Tuple{Symbol, Symbol, Symbol}, NamedTuple{(:modules, :sitename, :pages), Tuple{Vector{Module}, String, Vector{Pair{String, String}}}}})
@ Documenter ~/.julia/packages/Documenter/bYYzK/src/Documenter.jl:272
[8] top-level scope
@ ~/Repositories/Julia/Manopt.jl/docs/make2.jl:10
in expression starting at /Users/ronnber/Repositories/Julia/Manopt.jl/docs/make2.jl:10
but no warnings that the cites do not exist before, still also no single rendered output html page. If I remove said references file (still not bibliography command in the index.md) I only get warnings about non existing links of course.
I am not sure what this error is trying to tell me. Seems like it wants to treat a BibTeX entry as a heading?
edit: The error appears as soon as I have a reference to be linked/added in the literature of a canonical bibliography. So If
- I have no single
@cite
all works fine (and the bibliography global block is empty). - If I have a single cite and a canonical bibliography block (e.g. in my references.md) the error above appears
- If I have the
@bibliography
block (either in references.md or index.md) set to non canonical, it renders, but no links work
from documentercitations.jl.
If I do
import Documenter.Utilities.header_level
using BibInternal
header_level(::BibInternal.Entry) = 0
I get a bit further until I hit
ERROR: LoadError: type Entry has no field text
Stacktrace:
[1] getproperty(x::BibInternal.Entry, f::Symbol)
@ Base ./Base.jl:37
[2] domify(ctx::Documenter.Writers.HTMLWriter.HTMLContext, navnode::Documenter.Documents.NavNode, contents::Documenter.Documents.ContentsNode)
@ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/bYYzK/src/Writers/HTMLWriter.jl:1513
[3] (::Documenter.Writers.HTMLWriter.var"#78#79"{Documenter.Writers.HTMLWriter.HTMLContext, Documenter.Documents.NavNode, Documenter.Documents.Page})(elem::Markdown.Code)
@ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/bYYzK/src/Writers/HTMLWriter.jl:1453
but I fear I might be missing something tremendously before that I get the first error actually? I am just not sure what and I am lost by now.
from documentercitations.jl.
Not sure if related, but note that Documenter works with all markdown files in src
not just files in the pages = ...
keyword argument. This
(and that not even yet entered into the menu
got me thinking perhaps you have some garbage files left from previous tries in src
?
from documentercitations.jl.
I am aware that Documenter renders all markdown,
But, no, sadly not that I am aware of. Everything works fine as long as long as I have either zero cites or no canonical bibliography. As soon as I have both, it seems fail to reference the bib entries since those do not have a header level?
from documentercitations.jl.
Can you try using this .bib
file? Just to test it? I’m thinking there’s something in your .bib
file that’s tripping up the system.
from documentercitations.jl.
Sure, will try. My current file is already really minimal and just
@book{AbsilMahonySepulchre:2008,
title = {Optimization Algorithms on Matrix Manifolds},
author = {Absil, P.-A. and Mahony, R. and Sepulchre, R.},
year = {2008},
publisher = {Princeton University Press},
doi = {10.1515/9781400830244}
}
from documentercitations.jl.
Try removing the colon from the key name
from documentercitations.jl.
I did try that a lot of times already, that does not change anything.
from documentercitations.jl.
Ok, very weird… I’ll try to dig into this when I’m back at my computer
from documentercitations.jl.
No problem, I will try to narrow it down to a as-few-as-possible-file/lines example later today.
from documentercitations.jl.
Did you restart Julia in between? Perhaps the caching is causing the problem if it has already cached some bad entry?
from documentercitations.jl.
I usually start my documenter run from terminal, since there I can decide with --quarto
whether to render quarto stuff before running documenter or not. So Julia is indeed specifically started to run Documenter.
from documentercitations.jl.
Can you try using this
.bib
file? Just to test it? I’m thinking there’s something in your.bib
file that’s tripping up the system.
The error also appears when I switch from my references.bib
to your refs.bib
(ignoring the missing cite keys I get) and additionally writing [Evans1983](@cite)
in my index.md (running make2.jl
, my minimal file atop). So it is most probably not the bib file.
edit: even when my index md is the only file with citation code and is minimised to
[Evans1983](@cite)
```@bibliography
Pages = ["index.md"]
```
from documentercitations.jl.
Okay, that’s good to know, at least
from documentercitations.jl.
So! I went first for the approach of an MWE, but that suddenly worked, so I slowly in a binary fashion deleted files from (a copy of) my relatively large documentation to find the page that issues the error. 😴
But then 🤓
If you do a src/references.bib
as
@book{AbsilMahonySepulchre:2008,
title = {Optimization Algorithms on Matrix Manifolds},
author = {Absil, P.-A. and Mahony, R. and Sepulchre, R.},
year = {2008},
publisher = {Princeton University Press},
doi = {10.1515/9781400830244}
}
and an src/index.md
as
```@contents
Depth = 3
```
[AbsilMahonySepulchre:2008](@cite)
```@bibliography
```
and a make.jl
like (make sure to have Documenter
, DocumenterCitations
and here Manopt
in your environment)
using Pkg
Pkg.activate(@__DIR__)
using Manopt, Documenter, DocumenterCitations
# (e) ...finally! make docs
bib = CitationBibliography(joinpath(@__DIR__, "src", "references.bib"); style=:authoryear)
makedocs(bib;
modules=[Manopt],
sitename="Manopt.jl",
pages=[
"Home" => "index.md",
],
)
deploydocs(; repo="github.com/JuliaManifolds/Manopt.jl", push_preview=true)
That one fails!
So it seems to be some interplay between table of contents and bibliography!
Luckily at least for some time I can ignore the @contents
(in the long run for accessibility I would prefer to have that).
On the other hand – luckily – it is not Quarto or something causing this, but indeed Documenter itself.
from documentercitations.jl.
Ah, so this is the "old" issue ali-ramadhan/DocumenterCitations.jl#24
Well, good to know that's still an issue, I guess.
We'll have to really figure out why that happens and fix it at some point.
I'm sorry this caused you so much trouble. Quite a rabbit hole!
For now, my recommendation would be to have your canonical reference on a separate page, and specifically not in index.md
, where you probably have @contents
.
from documentercitations.jl.
Well, it was not that nice to start with this.
It does not matter whether @contents
and the literature are on the same markdown file. my @contents
was on a separate lists.md
file somewhere far away from my references.md
(canonical) or my local ones I will to per page.
And I was not aware that this was even an old issue, well. Now I wasted this afternoon. It is what it is, and at least now it seems to work and I just have to rewrite my two styles of references into one (but hopefully only do such thing once).
from documentercitations.jl.
Yeah, I understand. I'm sorry about the frustrating experience.
We'll definitely look into improving this situation, but it might take some time.
from documentercitations.jl.
It does not matter whether @contents and the literature are on the same markdown file.
Right! So based on ali-ramadhan/DocumenterCitations.jl#24 (comment) and ali-ramadhan/DocumenterCitations.jl#33 (comment), as well as my own testing just now, the current workaround is to have your canonical bibliography on a separate page, and exclude that page from the Pages
list of any @contents
block.
Definitely not an ideal situation.
from documentercitations.jl.
Now that I can reproduce this, I'm not sure if this is really a bug in DocumenterCitations.jl
, or in Documenter.jl
.
The error gets triggered by the code handling the @contents
block. It processes the content of the listed pages and for some reason gets to a point where it wants to know the header_level
of a bibtex entry.
@fredrikekre Should we open an issue for this at https://github.com/JuliaDocs/Documenter.jl/issues? Or maybe we should figure out exactly why this happens, first.
from documentercitations.jl.
Does it also error when you use #3 and Documenter#master? With all the changes to the AST-related internals, maybe this has fixed itself.
from documentercitations.jl.
Does it also error when you use #3 and Documenter#master
Unfortunately, yes. But in the latest iteration of #3 I've added a @test_broken
case to track this. So I should be able to get to the bottom of this, soonish.
from documentercitations.jl.
Related Issues (20)
- Incompatible with `linkcheck` HOT 2
- Note = not displayed (or: add customs fields in display of a BibteX entry) HOT 5
- Render citation from docs also in in REPL HOT 7
- About non canonical bibliography inconsistencies (to autodocs) HOT 4
- Allow to exclude specific entries from the bibliography
- Duplicate keys in `:alpha`betic style HOT 12
- How to use `:numeric` but with `:nyt` sorting HOT 6
- doctest and CitationBibliography HOT 11
- Add support for bioRxiv and HAL preprint servers
- Citations from docstrings are not collected HOT 5
- Transform citations with missing references HOT 1
- Add support for corporate authors HOT 5
- This package fails PkgEval HOT 9
- Support `urldate` field HOT 2
- DocumenterCitations 1.3.0 is a breaking change? HOT 24
- Markdown syntax in strings in BibTeX entries is not escaped HOT 4
- Any valid BibTeX entry should be able to auto-link both a URL and a DOI
- Show reference on hover HOT 1
- Backlinks
- Use multiple .bib files to create citation
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 documentercitations.jl.