I’m having a little problem with the internals of
Documenter.jl, in the context of a fork of
DocumenterCitation I’m working on (
It seems that running
makedocs overwrites docstrings of the loaded package. I haven’t been able to figure out where in Documenter’s code this is happening or how I might avoid it.
What I’m doing in the plugin is modifying the values of
page is one of the pages in
doc is the main
Documenter.Documents.Document. Specifically, I’m modifying markdown links like
[GoerzQ2022](@cite) in-place to something like
[](<link to bibliography>).
The problem is that these replacements end up back in the actual docstrings. For example, in the test-REPL for the
QuantumCitations package itself (
julia> using QuantumCitations help?> QuantumCitations.Example Example An example object citing Ref. GoerzQ2022 (@cite) with a "References" section in its docstring. References ≡≡≡≡≡≡≡≡≡≡≡≡ • GoerzQ2022 (@cite) Goerz et al. Quantum 6, 871 (2022) julia> include("docs/make.jl") Starting makedocs ... help?> QuantumCitations.Example Example An example object citing Ref.  (../references/#GoerzQ2022) with a "References" section in its docstring. References ≡≡≡≡≡≡≡≡≡≡≡≡ •  (../references/#GoerzQ2022) Goerz et al. Quantum 6, 871 (2022)
Note how the original
@cite have been replaced in the REPL docs!
The real problem with this is that it breaks running
makedocs a second time in the same REPL (as I like to do while I’m working on the documentation): on the second run, the plugin picks up the modified docstring, and then doesn’t recognize the link as a citation.
- Where in
Documenter.jldoes this happen?
- Why does this happen? Is this a bug in Documenter? I feel like doing replacements while rendering the documentation to HTML shouldn’t affect docstrings in the REPL at all.
- What can I do to get around this? Can I clear the docstring cache after