@contents and any canonical bibliography do not work together about documentercitations.jl HOT 28 CLOSED

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.