Adapt documentation from "QuantumCitations" fork

[goerz]

This makes the documentation appropriate for QuantumCitations having been merged back into DocumenterCitations.

The default style (following QuantumCitations) has changed to :numeric, making this a breaking change. The differences to the previous version of DocumenterCitations are outlined in NEWS.md, serving as a guideline for any users switching to the next release of DocumenterCitations, but wanting to keep the existing author-year style citations.

[goerz]

I've set version = "0.3.0-dev", in anticipation of this being released as v0.3.0 (breaking release). There are a few places in the documentation where I explicitly talk about "pre/post v0.3.0", to help any user who wants to switch to the new release, but keep their existing author-year citation style.

[goerz]

Please also review the README.md and NEWS.md at https://github.com/JuliaDocs/DocumenterCitations.jl/tree/mg/update-documentation.

It seems to me that merging this actually completes re-integrating QuantumCitations back into DocumenterCitations. We should be able to make a release based on this. It might be a good idea to test things out for a few days, though. For example, maybe someone (other than me) with an existing project using DocumenterCitations should try out the new master branch and see if everything works for them.

[goerz]

Good catch in #5… let me rebase this

[goerz]

For the record: the easiest way to review the rendered documentation locally is to run make servedocs in a checkout of this branch. Or, if you're on Windows or otherwise prefer not to use make, run julia --project=test and

julia> include("devrepl.jl")
julia> servedocs(port=8000, verbose=true)

[fredrikekre]

From #3, I think the only API thing that needs to be discussed is the return value of format_citation, if that is even considered public API. Right now it return either a string, or a vector of markdown segments. In #3 it is updated to be a MarkdownAST.Paragraph consistently, but this one is slightly more convoluted to construct as a user who just want to implement a custom style. Perhaps it can return a markdown string consistently and we parse and convert internally?

[goerz]

From #3, I think the only API thing that needs to be discussed is the return value of format_citation, if that is even considered public API.

At least post-1.0, I would prefer not to consider it (or anything detailed in Internals) part of the public API. And I agree, we can probably adapt to the next Documenter version without making any breaking changes.

Right now it return either a string, or a vector of markdown segments. In #3 it is updated to be a MarkdownAST.Paragraph consistently, but this one is slightly more convoluted to construct as a user who just want to implement a custom style. Perhaps it can return a markdown string consistently and we parse and convert internally?

Returning a markdown string that then gets parsed and inserted into the output tree is exactly the behavior I would like, see #6

[mortenpi]

I don't have any strong opinions here, and nothing stood out when I skimmed through the PR 🙂

The only suggestion I would have is to adopt the keep a changelog format for the changelog/NEWS.md. This would make it consistent with Documenter, and you could potentially benefit from some automated tooling in the future: https://github.com/JuliaDocs/Documenter.jl/blob/master/CHANGELOG.md

[goerz]

The only suggestion I would have is to adopt the keep a changelog format for the changelog/NEWS.md.

Sounds good to me! I've changed the format of NEWS.md accordingly.