Fix incompatibility of @bibliography and @contents

Use an independent `AnchorMap` to keep track of targets in the canonical `@bibliography` blocks.
JuliaDocs · Sep 20, 2023 · d9bb2bf · d9bb2bf
1 parent 5a66543
commit d9bb2bf
Show file tree

Hide file tree

Showing 7 changed files with 36 additions and 17 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -4,6 +4,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased][]
+
+### Fixed
+
+* It is now possible to have a page that contains a `@bibliography` block listed in [`@contents`](https://documenter.juliadocs.org/stable/man/syntax/index.html#@contents-block) [[#16][]].
+
+
 ## [Version 1.2.0][1.2.0] - 2023-09-16
 
 ### Version changes
@@ -76,3 +83,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#31]: https://github.com/JuliaDocs/DocumenterCitations.jl/pull/31
 [#20]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/20
 [#19]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/19
+[#16]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/16
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "DocumenterCitations"
 uuid = "daee34ce-89f3-4625-b898-19384cb65244"
 authors = ["Michael Goerz <[email protected]>"]
-version = "1.2.0"
+version = "1.2.1-dev"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -85,7 +85,6 @@ bib = CitationBibliography(
 makedocs(;
     authors=AUTHORS,
     sitename="DocumenterCitations.jl",
-    strict=true,
     format=Documenter.HTML(
         prettyurls=true,
         canonical="https://juliaquantumcontrol.github.io/DocumenterCitations.jl",

diff --git a/src/DocumenterCitations.jl b/src/DocumenterCitations.jl
@@ -22,9 +22,8 @@ export CitationBibliography
 bib = CitationBibliography(bibfile; style=:numeric)
 ```
 
-instantiates a plugin that must be passed as an (undocumented!) positional
-argument to
-[`Documenter.makedocs`](https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs).
+instantiates a plugin object that must be passed as an element of the `plugins`
+keyword argument to [`Documenter.makedocs`](https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs).
 
 # Arguments
 
@@ -43,6 +42,9 @@ should not be considered part of the stable API.
 * `citations`: ordered dict of citation key to citation number
 * `page_citations`: dict of page file name to set of citation keys cited on
   page.
+* `anchor_map`: an [`AnchorMap`](https://documenter.juliadocs.org/stable/lib/internals/anchors/#Documenter.AnchorMap)
+  object that keeps track of the link anchors for references in bibliography
+  blocks
 """
 struct CitationBibliography <: Documenter.Plugin
     # name of bib file
@@ -56,6 +58,9 @@ struct CitationBibliography <: Documenter.Plugin
     citations::OrderedDict{String,Int64}
     # page file name => set of citation keys (private)
     page_citations::Dict{String,Set{String}}
+    # AnchorMap object that stores the link anchors to all references in
+    # canonical bibliography blocks
+    anchor_map::Documenter.AnchorMap
 end
 
 function CitationBibliography(bibfile::AbstractString=""; style=nothing)
@@ -77,7 +82,15 @@ function CitationBibliography(bibfile::AbstractString=""; style=nothing)
     end
     citations = OrderedDict{String,Int64}()
     page_citations = Dict{String,Set{String}}()
-    return CitationBibliography(bibfile, style, entries, citations, page_citations)
+    anchor_map = Documenter.AnchorMap()
+    return CitationBibliography(
+        bibfile,
+        style,
+        entries,
+        citations,
+        page_citations,
+        anchor_map
+    )
 end
 
 

diff --git a/src/bibliography.jl b/src/bibliography.jl
@@ -439,7 +439,7 @@ function expand_bibliography(node::MarkdownAST.Node, meta, page, doc)
     if fields[:Canonical]
         html = """<div class="citation canonical"><$tag>"""
     end
-    headers = doc.internal.headers
+    anchors = bib.anchor_map
     entries = OrderedDict{String,Bibliography.Entry}(
         key => bib.entries[key] for key in keys_to_show
     )
@@ -454,7 +454,7 @@ function expand_bibliography(node::MarkdownAST.Node, meta, page, doc)
         @assert entry.id == key
         if fields[:Canonical]
             # Add anchor that citations can link to from anywhere in the docs.
-            if Documenter.anchor_exists(headers, key)
+            if Documenter.anchor_exists(anchors, key)
                 # Skip entries that already have a canonical bib entry
                 # elsewhere. This is expected behavior, not an error/warning,
                 # allowing to split the canonical bibliography in multiple
@@ -463,7 +463,7 @@ function expand_bibliography(node::MarkdownAST.Node, meta, page, doc)
                 continue
             else
                 @debug "Defining anchor for key=$(key)"
-                Documenter.anchor_add!(headers, entry, key, page.build)
+                Documenter.anchor_add!(anchors, entry, key, page.build)
             end
         else
             # For non-canonical bibliographies, no anchors are generated, and

diff --git a/src/citations.jl b/src/citations.jl
@@ -408,11 +408,11 @@ function expand_citation(node::MarkdownAST.Node, meta, page, doc)
     if haskey(bib.entries, key)
         entry = bib.entries[key]
         @assert entry.id == key
-        headers = doc.internal.headers
-        if Documenter.anchor_exists(headers, key)
-            if Documenter.anchor_isunique(headers, key)
+        anchors = bib.anchor_map
+        if Documenter.anchor_exists(anchors, key)
+            if Documenter.anchor_isunique(anchors, key)
                 # Replace the `@cite` url with a path to the referenced header.
-                anchor = Documenter.anchor(headers, key)
+                anchor = Documenter.anchor(anchors, key)
                 path   = relpath(anchor.file, dirname(page.build))
                 if isnothing(cit.link_text)
                     @assert length(node.children) == 1 &&

diff --git a/test/test_content_block.jl b/test/test_content_block.jl
@@ -22,13 +22,12 @@ include("run_makedocs.jl")
     ) do dir, result, success, backtrace, output
         #if !success
         #    println("")
-        #    @error "Failed makedocs:\n$output" dir  # XXX
+        #    @error "Failed makedocs:\n$output" dir
         #end
         #if result isa Exception
-        #    @error "Raised $(typeof(result))\n" result  # XXX
+        #    @error "Raised $(typeof(result))\n" result
         #end
-        @test result == ErrorException("type Entry has no field level")  # XXX
-        @test_broken success
+        @test success
     end
 
 end