Add support for [text](@cite key) syntax

[goerz]

Closes #63

[fredrikekre]

This is great! I was just about to implement this but looked and open PRs and found this. I think that

DocumenterCitations.jl/src/citations.jl

Line 28 in 13f5a73

if length(link.text) === 1 && isa(link.text[1], String)

is only true for the [key](@cite) style, in general.

[goerz]

For the record, this functionality is also fully implemented in QuantumCitations, which is my fork of DocumenterCitations.

[fredrikekre]

Ok... Why not contribute to existing packages to join efforts instead of forking?

[goerz]

I tried, with this PR. Unfortunately, DocumenterCitations seems to be unmaintained. There’s also a question of control: if I’m depending on a plugin like this in the documentation of my projects, I need to have a fair amount of control to implement any feature I might need. My preference would have been to extend this package instead of forking, but that would require an active and responsive maintainer. This is not a criticism of @ali-ramadhan, but a fork seemed like the way to go here. That being said, QuantumCitations could in principle be backported, although there are large parts that were substantially rewritten to support “citation order” / only listing cited entries in the bibliography.

[vchuravy]

Maybe it would make sense to move this package to JuliaDocs?

[fredrikekre]

I can invite @ali-ramadhan to JuliaDocs if you want to transfer it there.

[goerz]

I’d certainly be open to (co-) maintaining this package within the JuliaDocs org, but it’s up to @ali-ramadhan

[goerz]

@simonbyrne and @LazyScholar seem to also have had maintainer access in the past

[simonbyrne]

I agree it would make sense to move, but I don't have admin access. @vchuravy is Ali still at MIT? Can you reach out to him?

As far as this PR goes, a test and/or example that uses this would be helpful.

[fredrikekre]

Bump!

[fredrikekre]

Bump @ali-ramadhan 🙂

[navidcy]

@ali-ramadhan?

[charleskawczynski]

Can we somehow add a test?

[simonbyrne]

Given that the current admin is missing, we could also just fork it to JuliaDocs and move development there (similar to what we had to do for https://github.com/JuliaFolds2)

[fredrikekre]

Forked: https://github.com/JuliaDocs/DocumenterCitations.jl

[goerz]

Can we somehow add a test?

I'm not going to pursue this PR further in its current form. For context, this PR was a "test balloon" to see if DocumenterCitations was open to contributions (which it currently is not). Hence, I forked the package. The full feature, including extensive tests, is implemented in the forked QuantumCitations.jl. That fork also includes several other additions which would close #61, #26, #22, and #14. However, it also turned into a substantial rewrite, including some changes to how the citation pipeline runs. This was necessary to enable my preferred numbered citation schemes, where the citations are numbered in the order they appear throughout the entire documentation. This required separating "collecting" citations from rendering them.

There are still some limitations, most notably a "bug" in Documenter described in https://discourse.julialang.org/t/running-makedocs-overwrites-repl-docstrings/95982. This would be fixed in Documenter 0.28 (whenever that will come out), and the changes in Documenter 0.28 would also allow for doing some more advances rendering of citations, such as collapsing the citations in the first paragraph of https://juliaquantumcontrol.github.io/QuantumControl.jl/stable/, which should render as "[1-8]". However, Documenter 0.28 is very breaking, and might again require some fairly extensive restructuring in DocumenterCitations/QuantumCitations, which I'm planning to make when that version comes out (and I have some spare time).

The QuantumCitations package is functionally backward compatible with DocumenterCitations, except that the defaults are different. If I was going to backport all the functionality into DocumenterCitations, I could again make the Author-year style the default, and just switch my packages to the Numeric style.

Thus, from my perspective, the way to go would be

• DocumenterCitations gets forked to the JuliaDocs organization
• Documenter 0.28 comes out
• I adapt QuantumCitations to Documenter 0.28
• I make a wholesale PR to DocumenterCitations to introduce all the changes from QuantumCitations. Basically, this will come down to renaming QuantumCitations to DocumenterCitations and changing the default to be "Author-Year" style, so as not to break rendering for existing users.
• Additional features such as collapsing citations will be added to the new DocumenterCitations.
• QuantumCitations will either go away or become a light-weight package that simply switches the default style to numeric

There would have to a responsive maintainer for the JuliaDocs/DocumenterCitations fork to oversee this… Or if you wanted to add me as a maintainer there, I could just go ahead and do the rewrite when the time comes.

[fredrikekre]

You should already have gotten an invitation.

[fredrikekre]

Lets discuss the next steps in JuliaDocs/DocumenterCitations.jl#1

[goerz]

Lets discuss the next steps in JuliaDocs#1

Yes… I'll get back to you there later tonight

I'm not going to pursue this PR further in its current form.

So, I'm just going to close this for now, and we can revisit the issue over at JuliaDocs