Compatibility with Documenter 1.0

[fredrikekre]

Edit (@goerz):

As a side-effect:

Closes #19

[fredrikekre]

Tests pass and docs build, but some things don't quite work yet.

[goerz]

I’ll have a look at these (on my phone right now). As a heads-up: I already adapted the documentation this morning, and I’ll push that branch and make a PR later today.

[goerz]

This is the least important aspect of this PR, but just for the record: To get the "Codestyle" CI to pass, run make codestyle in your checkout. Or, to do it manually (if you don't have make):

julia --project=test
julia> using JuliaFormatter
julia> format(["src", "docs", "test"])

The relevant rules are in the .JuliaFormatter.toml file in the root of the repo. I'm not particular to any specific setting, but having everything auto-formatted for consistency makes life much easier, and especially keeps out stuff like trailing whitespace.

[fredrikekre]

Okay, this branch is ready now I think but let's leave it unmerged until Documenter is released. Users that want to use Documenter#master can use this branch for now.

[fredrikekre]

Looks like this branch does not expand citations in docstrings. I wonder if the order within documenter have changed.

[fredrikekre]

@mortenpi it looks like the tree iterator here doesn't reach all the way to the docstrings now, but stop at Documenter.DocsNode([...]). Any ideas how to fix?

[goerz]

Thanks so much for helping with adapting this to the upcoming Documenter release, guys!

Okay, this branch is ready now I think but let's leave it unmerged until Documenter is released.

Yes, let's slow down with this a little for now, if that's ok… Especially because I gotta go and work on my JuliaCon talk for a bit 😉. But after that, I'll need to get my head back into the internals and look through everything in detail.

I'd like to add a test that the issue that I described in https://discourse.julialang.org/t/running-makedocs-overwrites-repl-docstrings/95982 is gone with the new Documenter version, and that the workaround in

DocumenterCitations.jl/src/DocumenterCitations.jl

Lines 21 to 28 in 7b235fd

	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.

is no longer necessary. That is, one can hopefully run docs/make.jl twice in the same REPL without it causing any problems.

I'd also want to think through the implications of #6 for how exactly format_citation should tie into the internals with the new Documenter version.

[mortenpi]

@mortenpi it looks like the tree iterator here doesn't reach all the way to the docstrings now, but stop at Documenter.DocsNode([...]). Any ideas how to fix?

You need to explicitly dive into the .element: https://github.com/JuliaDocs/Documenter.jl/blob/7c97a86a31e360d7d22082a9a783b0cab24163b5/src/documents.jl#L145-L148

E.g. something like what is done here: https://github.com/JuliaDocs/Documenter.jl/blob/7c97a86a31e360d7d22082a9a783b0cab24163b5/src/CrossReferences.jl#L31-L53

This should eventually be changed though, and the docstrings should become proper child nodes.

[goerz]

Just a heads-up: I was able to rebase this on top of #32 and make further modifications that get everything working perfectly with today's master of Documenter.

This includes expanding citations in docstrings. The caching workaround is no longer needed. Also, #19 solved itself 🎉. Not sure yet about #16.

I'll wait with force-pushing the changes to this PR until after #32 is merged (stacking more than two PRs just gets a little too messy).

In any case, I think I can take it from here, and there shouldn't be any problem whatsoever with being compatible with Documenter 1.0 as soon as it's released.

Thanks again for helping me to get the conversion started!

[fredrikekre]

Great, thanks. Wanted to pick this up but didn't find the time.

[goerz]

@fredrikekre @mortenpi Congratulations on the Documenter 1.0 release!

I would still like to merge #35 first and make a 1.1 release based on that (still compatible with Documenter 0.27).

But after that, this PR should be ready to merge, and would then be the 1.2 release. There is of course a "breaking change" in that the plugin now has to be passed to makedocs via the plugin keyword argument instead of as a positional argument, but I would consider that a breaking change in Documenter, not DocumenterCitations. So a minor release should be okay.

Two small details that still need to be fixed in this PR:

• There's a failing test on Windows (I tink due to an issue with platfrom-specific line endings, for a file I'm loading to compare output against)
• We should remove the dev-install of Documenter in the CI and local tooling

[goerz]

Ok, fixed those two remaining issues…

This should now be ready for final review. It would still have to be rebased after merging #35 and making the 1.1 release.

[goerz]

Oh, and NEWS.md will have to be updated

[goerz]

Preview: https://juliadocs.org/DocumenterCitations.jl/previews/PR3/

[fredrikekre]

Can't approve my own PR but looks good.

[mortenpi]

There is of course a "breaking change" in that the plugin now has to be passed to makedocs via the plugin keyword argument instead of as a positional argument, but I would consider that a breaking change in Documenter, not DocumenterCitations. So a minor release should be okay.

Agreed, this is a change in Documenter's interface, not DocumenterCitations'. Documenter users should have an explicit compat on Documenter to avoid any issues with this.