-
Notifications
You must be signed in to change notification settings - Fork 11
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: first working version for DocumenterCitations #139
Merged
Merged
Changes from 6 commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
23aa6e4
feat: first working version for DocumenterCitations
asinghvi17 3aa8df1
MAST -> MarkdownAST
asinghvi17 75562e5
Copy files from DocumenterCitations over to the DV docs to serve as a…
asinghvi17 93b44d1
Merge pull request #1 from LuxDL/as/th/cite
thofma 8ec9d4f
add dep
thofma 5b3de55
delete file that we want to copy?
thofma 6b3e792
Update src/vitepress_config.jl
asinghvi17 2e90a89
Bump version
asinghvi17 9fdc5aa
Add `refs.bib` back, comment the copying code out
asinghvi17 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,4 @@ | ||
[deps] | ||
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" | ||
DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365" | ||
DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,197 @@ | ||
# DocumenterCitations.jl integration | ||
|
||
This page shows the DocumenterCitations.jl integration and what it looks like. You can use DocumenterCitations in DocumenterVitepress in the same way that you use them in Documenter! | ||
|
||
This page's source was taken from the DocumenterCitations docs and rendered via DocumenterVitepress. | ||
|
||
# [Citation Style Gallery](@id gallery) | ||
|
||
The citation style is determined when instantiating the `CitationBibliography`, via the `style` argument. | ||
|
||
The built-in styles are: | ||
|
||
* `style=:numeric` (default): [numeric style](@ref numeric_style) | ||
* `style=:authoryear`: [author-year style](@ref author_year_style) | ||
* `style=:alpha`: [alphabetic style](@ref alphabetic_style) | ||
|
||
## [Numeric style](@id numeric_style) | ||
|
||
This is the default style (`style=:numeric`) used throughout the other pages of this documentation, cf. the Syntax examples. | ||
|
||
* `[GoerzQ2022](@cite)` renders as "[GoerzQ2022](@cite)" | ||
* `[FuerstNJP2014,SolaAAMOP2018](@cite)` renders as "[FuerstNJP2014,SolaAAMOP2018](@cite)" | ||
* `[GoerzQ2022](@citet)` renders as "[GoerzQ2022](@citet)" | ||
* `[GoerzQ2022](@citep)` renders as "[GoerzQ2022](@citep)" — `@citep` is the same as `@cite` for this style | ||
* `[GoerzQ2022; Eq. (1)](@cite)` renders as "[GoerzQ2022; Eq. (1)](@cite)" | ||
* `[GoerzQ2022; Eq. (1)](@citet)` renders as "[GoerzQ2022; Eq. (1)](@citet)" | ||
* `[GoerzQ2022](@citet*)` renders as "[GoerzQ2022](@citet*)" | ||
* `[GoerzQ2022; Eq. (1)](@citet*)` renders as "[GoerzQ2022; Eq. (1)](@citet*)" | ||
* `[WinckelIP2008](@citet)` renders as "[WinckelIP2008](@citet)" | ||
* `[WinckelIP2008](@Citet)` renders as "[WinckelIP2008](@Citet)" | ||
* `[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@cite)` renders as "[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@cite)" | ||
* `[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@Citet)` renders as "[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@Citet)" | ||
* `[arbitrary text](@cite GoerzQ2022)` renders as "[arbitrary text](@cite GoerzQ2022)" | ||
|
||
**References:** | ||
|
||
```@bibliography | ||
Pages = [@__FILE__] | ||
Style = :numeric | ||
Canonical = false | ||
``` | ||
|
||
## [Author-year style](@id author_year_style) | ||
|
||
The author-year style (`style=:authoryear`) formats citations with the author name and publication year. This is the citation style used, e.g., in [Rev. Mod. Phys.](https://journals.aps.org/rmp/) (`rmp` option in [REVTeX](https://www.ctan.org/tex-archive/macros/latex/contrib/revtex/auguide)). The bibliography is sorted alphabetically by author name. The default `@cite` command is parenthetical (`@cite` and `@citep` are equivalent) which is different from the `authoryear` style in [natbib](https://mirrors.rit.edu/CTAN/macros/latex/contrib/natbib/natnotes.pdf). | ||
|
||
* `[GoerzQ2022](@cite)` renders as "[GoerzQ2022](@cite%authoryear%)" | ||
* `[FuerstNJP2014,SolaAAMOP2018](@cite)` renders as "[FuerstNJP2014,SolaAAMOP2018](@cite%authoryear%)" | ||
* `[GoerzQ2022](@citet)` renders as "[GoerzQ2022](@citet%authoryear%)" | ||
* `[GoerzQ2022](@citep)` renders as "[GoerzQ2022](@citep%authoryear%)" — `@citep` is the same as `@cite` for this style | ||
* `[GoerzQ2022; Eq. (1)](@cite)` renders as "[GoerzQ2022; Eq. (1)](@cite%authoryear%)" | ||
* `[GoerzQ2022; Eq. (1)](@citet)` renders as "[GoerzQ2022; Eq. (1)](@citet%authoryear%)" | ||
* `[GoerzQ2022](@cite*)` renders as "[GoerzQ2022](@cite*%authoryear%)" | ||
* `[GoerzQ2022](@citet*)` renders as "[GoerzQ2022](@citet*%authoryear%)" | ||
* `[GoerzQ2022; Eq. (1)](@cite*)` renders as "[GoerzQ2022; Eq. (1)](@cite*%authoryear%)" | ||
* `[GoerzQ2022; Eq. (1)](@citet*)` renders as "[GoerzQ2022; Eq. (1)](@citet*%authoryear%)" | ||
* `[WinckelIP2008](@citet)` renders as "[WinckelIP2008](@citet%authoryear%)" | ||
* `[WinckelIP2008](@Citet)` renders as "[WinckelIP2008](@Citet%authoryear%)" | ||
* `[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@cite)` renders as "[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@cite%authoryear%)" | ||
* `[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@Citet)` renders as "[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@Citet%authoryear%)" | ||
* `[arbitrary text](@cite GoerzQ2022)` renders as "[arbitrary text](@cite GoerzQ2022)" | ||
|
||
**References:** | ||
|
||
```@bibliography | ||
Pages = [@__FILE__] | ||
Style = :authoryear | ||
Canonical = false | ||
``` | ||
|
||
## [Alphabetic style](@id alphabetic_style) | ||
|
||
The `style=:alpha` formats citations and references like `:numeric`, except that it uses labels derived from the author names and publication year and sorts the references alphabetically. | ||
|
||
* `[GoerzQ2022](@cite)` renders as "[GoerzQ2022](@cite%alpha%)" | ||
* `[FuerstNJP2014,SolaAAMOP2018](@cite)` renders as "[FuerstNJP2014,SolaAAMOP2018](@cite%alpha%)" | ||
* `[GoerzQ2022](@citet)` renders as "[GoerzQ2022](@citet%alpha%)" | ||
* `[GoerzQ2022](@citep)` renders as "[GoerzQ2022](@citep%alpha%)" — `@citep` is the same as `@cite` for this style | ||
* `[GoerzQ2022; Eq. (1)](@cite)` renders as "[GoerzQ2022; Eq. (1)](@cite%alpha%)" | ||
* `[GoerzQ2022; Eq. (1)](@citet)` renders as "[GoerzQ2022; Eq. (1)](@citet%alpha%)" | ||
* `[GoerzQ2022](@citet*)` renders as "[GoerzQ2022](@citet*%alpha%)" | ||
* `[GoerzQ2022; Eq. (1)](@citet*)` renders as "[GoerzQ2022; Eq. (1)](@citet*%alpha%)" | ||
* `[WinckelIP2008](@citet)` renders as "[WinckelIP2008](@citet%alpha%)" | ||
* `[WinckelIP2008](@Citet)` renders as "[WinckelIP2008](@Citet%alpha%)" | ||
* `[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@cite)` renders as "[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@cite%alpha%)". Note that unlike for `style=:numeric`, the citations are not compressed. | ||
* `[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@Citet)` renders as "[BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@Citet%alpha%)" | ||
* `[arbitrary text](@cite GoerzQ2022)` renders as "[arbitrary text](@cite GoerzQ2022)" | ||
|
||
**References:** | ||
|
||
```@bibliography | ||
Pages = [@__FILE__] | ||
Style = :alpha | ||
Canonical = false | ||
|
||
SolaAAMOP2018 | ||
``` | ||
|
||
```@raw latex | ||
Compared to the HTML version of the documentation, the hanging indent in the above list of references is too small for the longer labels of the \texttt{:alpha} style. This can be remedied by adjusting the \texttt{dl\_hangindent} and \texttt{dl\_labelwidth} parameters with \hyperlinkref{sec:customizing_latex_output}{\texttt{DocumenterCitations.set\_latex\_options}}. | ||
``` | ||
|
||
Note that the `:alpha` style is able to automatically disambiguate labels: | ||
|
||
```@bibliography | ||
Pages = [] | ||
Style = :alpha | ||
Canonical = false | ||
|
||
GraceJMO2007 | ||
GraceJPB2007 | ||
``` | ||
|
||
This works because the `DocumenterCitations` plugin automatically upgrades `style=:alpha` to the internal | ||
|
||
``` | ||
DocumenterCitations.AlphaStyle | ||
``` | ||
|
||
|
||
## [Custom styles](@id custom_styles) | ||
|
||
In the following, we show two examples for user-defined styles. See the notes on customization on how to generally define a custom style. | ||
|
||
### Custom style: enumerated author-year | ||
|
||
In this example, the `:authoryear` style is used, but the references are shown in an enumerated list. | ||
|
||
~~~@eval | ||
# custom styles are included in docs/make.jl, which is how we get around | ||
# world-age issues. | ||
using Markdown | ||
custom_style = joinpath(@__DIR__, "..", "custom_styles", "enumauthoryear.jl") | ||
if isfile(custom_style) | ||
Markdown.parse(""" | ||
```julia | ||
$(read(custom_style, String)) | ||
``` | ||
""") | ||
end | ||
~~~ | ||
|
||
The important part of the definition is in the last line, indicating that the References should be shown as an enumeration (ordered list, `<ol>`, in HTML), see below. Meanwhile, citations render exactly as with `style=:authoryear`: | ||
|
||
* `[GoerzQ2022](@cite)` renders as "[GoerzQ2022](@cite%enumauthoryear%)" | ||
* `[FuerstNJP2014,SolaAAMOP2018](@cite)` renders as "[FuerstNJP2014,SolaAAMOP2018](@cite%enumauthoryear%)" | ||
* `[WinckelIP2008](@Citet)` renders as "[WinckelIP2008](@Citet%enumauthoryear%)" | ||
|
||
**References:** | ||
|
||
```@bibliography | ||
Pages = [@__FILE__] | ||
Style = :enumauthoryear | ||
Canonical = false | ||
``` | ||
|
||
### Custom style: Citation-key labels | ||
|
||
In this less trivial example, a style similar to `:alpha` is used, using the citation keys in the `.bib` file as labels. This would be somewhat more appropriate with citation keys that are shorter that the ones used here (keys similar to those automatically generated with the `:alpha` style). | ||
|
||
~~~@eval | ||
# custom styles are included in docs/make.jl, which is how we get around | ||
# world-age issues. | ||
using Markdown | ||
custom_style = joinpath(@__DIR__, "..", "custom_styles", "keylabels.jl") | ||
if isfile(custom_style) | ||
Markdown.parse(""" | ||
```julia | ||
$(read(custom_style, String)) | ||
``` | ||
""") | ||
end | ||
~~~ | ||
|
||
* `[GoerzQ2022](@cite)` renders as "[GoerzQ2022](@cite%keylabels%)" | ||
* `[FuerstNJP2014,SolaAAMOP2018](@cite)` renders as "[FuerstNJP2014,SolaAAMOP2018](@cite%keylabels%)" | ||
* `[GoerzQ2022](@citet)` renders as "[GoerzQ2022](@citet%keylabels%)" | ||
* `[GoerzQ2022](@citep)` renders as "[GoerzQ2022](@citep%keylabels%)" — `@citep` is the same as `@cite` for this style | ||
* `[GoerzQ2022; Eq. (1)](@cite)` renders as "[GoerzQ2022; Eq. (1)](@cite%keylabels%)" | ||
* `[GoerzQ2022; Eq. (1)](@citet)` renders as "[GoerzQ2022; Eq. (1)](@citet%keylabels%)" | ||
* `[GoerzQ2022](@citet*)` renders as "[GoerzQ2022](@citet*%keylabels%)" | ||
* `[GoerzQ2022; Eq. (1)](@citet*)` renders as "[GoerzQ2022; Eq. (1)](@citet*%keylabels%)" | ||
* `[WinckelIP2008](@citet)` renders as "[WinckelIP2008](@citet%keylabels%)" | ||
* `[WinckelIP2008](@Citet)` renders as "[WinckelIP2008](@Citet%keylabels%)" | ||
* `[arbitrary text](@cite GoerzQ2022)` renders as "[arbitrary text](@cite GoerzQ2022)" | ||
|
||
**References:** | ||
|
||
```@bibliography | ||
Pages = [@__FILE__] | ||
Style = :keylabels | ||
Canonical = false | ||
``` | ||
|
||
```@raw latex | ||
As with the \texttt{:alpha} style, for \LaTeX{} output, the \texttt{dl\_hangindent} and \texttt{dl\_labelwidth} parameters should be adjusted with \hyperlinkref{sec:customizing_latex_output}{\texttt{DocumenterCitations.set\_latex\_options}} to obtain a more suitable hanging indent that matches the HTML version of this documentation. | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,100 @@ | ||
module DocumenterVitepressDocumenterCitationsExt | ||
|
||
using DocumenterCitations, DocumenterVitepress | ||
|
||
import DocumenterVitepress as DV | ||
using Documenter: MarkdownAST | ||
|
||
# TODO: | ||
# - List style (rendered vs unrendered) | ||
# - Loose vs tight lists | ||
# - handle :dl properly, we cannot use Markdown for this, since it cannot be represented | ||
# using pure Markdown. We need to insert HTML directly. | ||
# At the moment, we treat :dl as :ol | ||
function DV.render(io::IO, mime::MIME"text/plain", node::DV.MarkdownAST.Node, bibliography::DocumenterCitations.BibliographyNode, page, doc; kwargs...) | ||
|
||
println(io) | ||
println(io, "***") | ||
println(io, "# Bibliography") | ||
println(io) | ||
|
||
# Turn the list into a proper MarkdownAST.node | ||
bibnode = _bibliography_to_list(bibliography) | ||
|
||
return DV.render(io, mime, bibnode, bibnode.element, page, doc; kwargs...) | ||
end | ||
|
||
function _bibliography_to_list(bib::DocumenterCitations.BibliographyNode) | ||
# Construct a MarkdownAST.Node containing this list | ||
list = MarkdownAST.List(bib.list_style in [:ol, :dl] ? :ordered : :bullet, false) | ||
node = MarkdownAST.Node(list) | ||
for item in bib.items | ||
newitem = MarkdownAST.Node(MarkdownAST.Item()) | ||
push!(newitem.children, item.reference) | ||
push!(node.children, newitem) | ||
end | ||
node | ||
end | ||
|
||
# Below is the code intended for LaTeXWriter. | ||
#= | ||
function Documenter.LaTeXWriter.latex( | ||
lctx::Documenter.LaTeXWriter.Context, | ||
node::MarkdownAST.Node, | ||
bibliography::BibliographyNode | ||
) | ||
|
||
if bibliography.list_style == :ol | ||
texenv = "enumerate" | ||
elseif bibliography.list_style == :ul | ||
if _LATEX_OPTIONS[:ul_as_hanging] | ||
texenv = nothing | ||
else | ||
texenv = "itemize" | ||
end | ||
else | ||
@assert bibliography.list_style == :dl | ||
# We emulate a definition list manually with hangindent and labelwidth | ||
texenv = nothing | ||
end | ||
|
||
io = lctx.io | ||
|
||
function tex_item(n, item) | ||
if bibliography.list_style == :ul | ||
if _LATEX_OPTIONS[:ul_as_hanging] | ||
print(io, "\\hangindent=$(_LATEX_OPTIONS[:ul_hangindent]) ") | ||
else | ||
print(io, "\\item ") | ||
end | ||
elseif bibliography.list_style == :ol # enumerate | ||
print(io, "\\item ") | ||
else | ||
@assert bibliography.list_style == :dl | ||
print(io, "\\hangindent=$(_LATEX_OPTIONS[:dl_hangindent]) {") | ||
_labelbox(io; width=_LATEX_OPTIONS[:dl_labelwidth]) do | ||
Documenter.LaTeXWriter.latex(lctx, item.label.children) | ||
end | ||
print(io, "}") | ||
end | ||
end | ||
|
||
println(io, "{$(_LATEX_OPTIONS[:bib_blockformat])% @bibliography\n") | ||
_wrapblock(io, texenv) do | ||
for (n, item) in enumerate(bibliography.items) | ||
tex_item(n, item) | ||
if !isnothing(item.anchor_key) | ||
id = _hash(item.anchor_key) | ||
print(io, "\\hypertarget{", id, "}{}") | ||
end | ||
Documenter.LaTeXWriter.latex(lctx, item.reference.children) | ||
print(io, "\n\n") | ||
end | ||
end | ||
println(io, "}% end @bibliography") | ||
|
||
end | ||
|
||
=# | ||
|
||
end |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should be able to do that, I think Vitepress accepts pure HTML. I'm just not sure if the Markdown will still be picked up. We'll have to test but that can be done later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure