Compatibility with Documenter 1.0

This patch updates the code base so that it works with the breaking
release of Documenter 1.0.

NEWS.md

@@ -3,7 +3,19 @@
 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).
 
-## [Version v1.1.0][1.1.0] - 2023-09-15
+
+## [Version 1.2.0][1.2.0] - 2023-09-16
+
+### Version changes
+
+* Update to [Documenter 1.0](https://github.com/JuliaDocs/Documenter.jl/releases/tag/v1.0.0). The most notable user-facing breaking change in Documenter 1.0 affecting DocumenterCitations is that the `CitationBibliography` plugin object now has to be passed to `makedocs` as an element of the `plugins` keyword argument, instead of as a positional argument.
+
+### Fixed
+
+* The plugin no longer conflicts with the `linkcheck` option of `makedocs` ([#19][])
+
+
+## [Version 1.1.0][1.1.0] - 2023-09-15
 
 ### Fixed
 
@@ -28,7 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Added an internal function `init_bibliography!` that is called at the beginning of the `ExpandBibliography` pipeline step. This function is intended to initialize internal state either of the `style` object or the `CitationBibliography` plugin object before rendering any `@bibliography` blocks. This is used to generate unique citation labels for the new `AlphaStyle()`. For the other builtin styles, it is a no-op. Generally, `init_bibliography!` can help with implementing custom "stateful" styles.
 
 
-## [Version v1.0.0][1.0.0] - 2023-07-12
+## [Version 1.0.0][1.0.0] - 2023-07-12
 
 ### Version changes
 
@@ -54,10 +66,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * [DocumenterCitations](https://github.com/JuliaDocs/DocumenterCitations.jl) is now hosted under the [JuliaDocs](https://github.com/JuliaDocs) organization.
 
 
-[Unreleased]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v0.2.12...v1.0.0
 [#36]: https://github.com/JuliaDocs/DocumenterCitations.jl/pull/36
 [#35]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/35
 [#32]: https://github.com/JuliaDocs/DocumenterCitations.jl/pull/32
 [#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

Project.toml

@@ -1,17 +1,21 @@
 name = "DocumenterCitations"
 uuid = "daee34ce-89f3-4625-b898-19384cb65244"
 authors = ["Michael Goerz <[email protected]>"]
-version = "1.1.0"
+version = "1.2.0"
 
 [deps]
+AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
 Bibliography = "f1be7e48-bf82-45af-a471-ae754a193061"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 Unicode = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
 
 [compat]
+AbstractTrees = "^0.4"
 Bibliography = "^0.2"
-Documenter = "0.27"
+Documenter = "1"
+MarkdownAST = "^0.1"
 OrderedCollections = "1"
 julia = "^1.6"

README.md

@@ -36,15 +36,17 @@ to the `[deps]` section of the relevant `Project.toml` file.
 
 ## Usage
 
-*   Place a BibTeX [`refs.bib`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/src/refs.bib) file in the `docs/src` folder of your project.  Then, in [`docs/make.jl`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/make.jl), instantiate the `CitationBibliography` plugin and pass it to [`makedocs`](https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs):
+*   Place a BibTeX [`refs.bib`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/src/refs.bib) file in the `docs/src` folder of your project.  Then, in [`docs/make.jl`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/make.jl), instantiate the `CitationBibliography` plugin with the path to the `.bib` file. Assuming `Documenter >= 1.0`, pass the plugin object to [`makedocs`](https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs) as element of the `plugins` keyword argument:
 
     ```julia
     using DocumenterCitations
 
     bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"))
-    makedocs(bib, ...)
+    makedocs(; plugins=[bib], ...)
     ```
 
+    In older versions of [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl), `bib` had to be passed as a positional argument to `makedocs`.
+
 *   Optional, but recommended: [add CSS to properly format the bibliography](https://juliadocs.github.io/DocumenterCitations.jl/dev/styling/)
 
 *   Somewhere in your documentation include a markdown block

docs/custom_styles/keylabels.jl

@@ -1,7 +1,7 @@
-import DocumenterCitations
+import DocumenterCitations, MarkdownAST
 
 # we use some (undocumented) internal helper functions for formatting...
-using DocumenterCitations: format_names, tex2unicode, italicize_md_et_al
+using DocumenterCitations: format_names, tex2unicode
 
 DocumenterCitations.format_bibliography_reference(::Val{:keylabels}, entry) =
     DocumenterCitations.format_bibliography_reference(:numeric, entry)
@@ -26,9 +26,9 @@ function DocumenterCitations.format_citation(
             format_names(entry; names=:lastonly, and=true, et_al, et_al_text="*et al.*") |>
             tex2unicode
         capitalize && (names = uppercase(names[1]) * names[2:end])
-        link_text = italicize_md_et_al("$names $link_text")
+        link_text = "$names $link_text"
     end
-    return link_text
+    return link_text::String
 end
 
 DocumenterCitations.bib_sorting(::Val{:keylabels}) = :nyt  # name, year, title

docs/make.jl

@@ -15,19 +15,18 @@ bib = CitationBibliography(
 
 println("Starting makedocs")
 
-include(joinpath("custom_styles", "enumauthoryear.jl"))
-include(joinpath("custom_styles", "keylabels.jl"))
+include("custom_styles/enumauthoryear.jl")
+include("custom_styles/keylabels.jl")
 
 makedocs(
-    bib,
     authors=AUTHORS,
+    linkcheck=true,
     sitename="DocumenterCitations.jl",
-    strict=true,
     format=Documenter.HTML(
         prettyurls=true,
         canonical="https://juliadocs.github.io/DocumenterCitations.jl",
         assets=String["assets/citations.css"],
-        footer="[$NAME.jl]($GITHUB) v$VERSION docs powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)."
+        footer="[$NAME.jl]($GITHUB) v$VERSION docs powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl).",
     ),
     pages=[
         "Home"                   => "index.md",
@@ -36,7 +35,8 @@ makedocs(
         "CSS Styling"            => "styling.md",
         "Internals"              => "internals.md",
         "References"             => "references.md",
-    ]
+    ],
+    plugins=[bib],
 )
 
 println("Finished makedocs")

docs/src/index.md

@@ -35,7 +35,7 @@ to the `[deps]` section of the relevant `Project.toml` file.
 
 ## Telling Documenter.jl about your bibliography
 
-First, place a BibTeX [`refs.bib`](./refs.bib) file in the `docs/src` folder of your project.  Then, in [`docs/make.jl`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/make.jl), instantiate the [`CitationBibliography`](@ref) plugin and pass it to [`makedocs`](https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs):
+First, place a BibTeX [`refs.bib`](./refs.bib) file in the `docs/src` folder of your project.  Then, in [`docs/make.jl`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/make.jl), instantiate the [`CitationBibliography`](@ref) plugin with the path to the `.bib` file. Assuming `Documenter >= 1.0`, pass the plugin object to [`makedocs`](https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs) as an element of the `plugins` keyword argument:
 
 ```julia
 using DocumenterCitations
@@ -44,10 +44,12 @@ bib = CitationBibliography(
     joinpath(@__DIR__, "src", "refs.bib");
     style=:numeric
 )
-makedocs(bib, ...)
+makedocs(; plugins=[bib], ...)
 ```
 
-To use the [author-year style](@ref author_year_style) that was the default prior to version 1.0, replace `style=:numeric` with `style=:authoryear`.
+In older versions of [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl), `bib` had to be passed as a positional argument to `makedocs`.
+
+To use the [author-year style](@ref author_year_style) that was the default prior to `DocumenterCitations` version 1.0, replace `style=:numeric` with `style=:authoryear`.
 
 Somewhere in your documentation, like a [References](@ref) page, include a markdown block
 
@@ -80,8 +82,7 @@ bib = CitationBibliography(
     style=:numeric  # default
 )
 
-makedocs(
-    bib,
+makedocs(;
     authors=AUTHORS,
     sitename="DocumenterCitations.jl",
     strict=true,
@@ -98,7 +99,8 @@ makedocs(
         "CSS Styling"            => "styling.md",
         "Internals"              => "internals.md",
         "References"             => "references.md",
-    ]
+    ],
+    plugins=[bib],
 )
 deploydocs(; repo="github.com/JuliaDocs/DocumenterCitations.jl.git")
 ```
@@ -115,9 +117,9 @@ Clicking on the citations takes you to the bibliography ("[References](@ref)").
 The following is a list of some projects that use `DocumenterCitations`:
 
 * [Oceananigans](https://clima.github.io/OceananigansDocumentation/stable/)
-* [QuantumPropagators](https://juliaquantumcontrol.github.io/QuantumPropagators.jl)
+* [QuantumPropagators](https://juliaquantumcontrol.github.io/QuantumPropagators.jl/)
 * [QuantumControl](https://juliaquantumcontrol.github.io/QuantumControl.jl/)
-* [TwoQubitWeylChamber](https://juliaquantumcontrol.github.io/TwoQubitWeylChamber.jl)
+* [TwoQubitWeylChamber](https://juliaquantumcontrol.github.io/TwoQubitWeylChamber.jl/)
 * [QuantumClifford](https://quantumsavory.github.io/QuantumClifford.jl/stable/references/) and the parent [QuantumSavory organization](https://github.com/QuantumSavory)
 
 ## Home References

docs/src/internals.md

@@ -12,7 +12,7 @@ CitationBibliography
 
 The [`DocumenterCitations.CitationBibliography`](@ref) plugin hooks into the [`Documenter.Builder.DocumentPipeline`](https://documenter.juliadocs.org/stable/lib/internals/builder/#Documenter.Builder.DocumentPipeline)[^1] between [`ExpandTemplates`](https://documenter.juliadocs.org/stable/lib/internals/builder/#Documenter.Builder.ExpandTemplates) (which expands `@docs` blocks) and [`CrossReferences`](https://documenter.juliadocs.org/stable/lib/internals/builder/#Documenter.Builder.CrossReferences). The plugin adds the following three steps:
 
-[^1]: See the documentation of [`Documenter.Utilities.Selectors`](https://documenter.juliadocs.org/stable/lib/internals/selectors/#Documenter.Utilities.Selectors) for an explanation of Documenter's pipeline concept.
+[^1]: See the documentation of [`Documenter.Selectors`](https://documenter.juliadocs.org/stable/lib/internals/selectors/#Documenter.Selectors) for an explanation of Documenter's pipeline concept.
 
 1. [`CollectCitations`](@ref)
 2. [`ExpandBibliography`](@ref)

docs/src/styling.md

@@ -19,13 +19,12 @@ The HTML generated by `DocumenterCitations` also uses CSS classes `canonical` an
 The `citations.css` file must be listed as an `asset` for `Documenter.HTML` in [`docs/make.jl`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/make.jl):
 
 ```julia
-makedocs(
-    bib,
-    # ...
+makedocs(;
     format = Documenter.HTML(
         # ...
         assets=String["assets/citations.css"],
     ),
+    plugins=[bib],
     # ...
 )
 ```

docs/src/syntax.md

@@ -191,7 +191,7 @@ While we try to be reasonably compatible, "Any `.bib` file will render the bibli
 
 Some tips to keep in mind when editing a `.bib` file to be used with `DocumenterCitations`:
 
-* Use unicode instead of [escaped symbols](http://www.bibtex.org/SpecialSymbols/).
+* Use unicode instead of [escaped symbols](https://www.bibtex.org/SpecialSymbols/).
 * You do not need to use [braces to protect capitalization](https://texfaq.org/FAQ-capbibtex). `DocumenterCitations` is not always able to remove such braces. But, unlike `bibtex`, `DocumenterCitation` will preserve the capitalization of titles.
 * Use a consistent scheme for citation keys. Shorter keys are better.
 * All entries should have a `Doi` field, or a `Url` field if no DOI is available.

src/DocumenterCitations.jl

@@ -1,32 +1,21 @@
 module DocumenterCitations
 
 using Documenter
-using Documenter.Anchors
 using Documenter.Builder
-using Documenter.Documents
 using Documenter.Selectors
-using Documenter.Utilities
 using Documenter.Expanders
 using Documenter.Writers.HTMLWriter
 
+import MarkdownAST
+import AbstractTrees
+
 using Markdown
 using Bibliography: Bibliography, xyear, xlink, xtitle
 using OrderedCollections: OrderedDict, OrderedSet
 using Unicode
 
 export CitationBibliography
 
-
-const _CACHED_CITATIONS = OrderedDict{String,Int64}()
-const _CACHED_PAGE_CITATIONS = OrderedDict{String,Set{String}}()
-# The caching is used to get around a Bug in Documenter 0.27, see
-# https://discourse.julialang.org/t/running-makedocs-overwrites-repl-docstrings
-# Even though it doesn't *really* solve the problem, caching `bib.citations`
-# and `bib.page_citation` in practice gets around the plugin not being able to
-# detect citations in docstring on a second call to `makedocs`. The caching
-# feature should be removed when Documenter 0.28 is released.
-
-
 """Plugin for enabling bibliographic citations in Documenter.jl.
 
 ```julia
@@ -69,14 +58,8 @@ struct CitationBibliography <: Documenter.Plugin
     page_citations::Dict{String,Set{String}}
 end
 
-function CitationBibliography(bibfile::AbstractString=""; style=nothing, cached=true)
-    # note: cached is undocumented (on purpose), see comment at
-    # _CACHED_PAGE_CITATIONS. Should be removed when Documenter 0.28 is
-    # released
+function CitationBibliography(bibfile::AbstractString=""; style=nothing)
     if isnothing(style)
-        @info "The 1.0 release of DocumenterCitations changed the default citation style from author-year to numeric. To restore the pre-1.0 default style, use `CitationBibliography(bibfile; style=:authoryear)`."
-        # The message is only to transition users through the breaking change
-        # in 1.0. It can be removed in any future 1.1 release.
         style = :numeric
         @debug "Using default style=$(repr(style))"
     elseif style == :alpha
@@ -92,16 +75,8 @@ function CitationBibliography(bibfile::AbstractString=""; style=nothing, cached=
             @warn "No entries loaded from $bibfile"
         end
     end
-    citations = Dict{String,Int64}()
+    citations = OrderedDict{String,Int64}()
     page_citations = Dict{String,Set{String}}()
-    if cached
-        citations = _CACHED_CITATIONS
-        page_citations = _CACHED_PAGE_CITATIONS
-        if (length(citations) > 0) || (length(page_citations) > 0)
-            @warn "Using cached citations"
-        end
-    end
-
     return CitationBibliography(bibfile, style, entries, citations, page_citations)
 end
 
@@ -170,4 +145,14 @@ include("citations.jl")
 include("bibliography.jl")
 include("formatting.jl")
 
+
+function __init__()
+    for errname in (:bibliography_block, :citations)
+        if !(errname in Documenter.ERROR_NAMES)
+            push!(Documenter.ERROR_NAMES, errname)
+        end
+    end
+end
+
+
 end