ali-ramadhan / documentercitations.jl Goto Github PK

DocumenterCitations.jl uses Bibliography.jl to add support for BibTeX citations and references in documentation pages generated by Documenter.jl.

Home Page: https://ali-ramadhan.github.io/DocumenterCitations.jl/dev

License: MIT License

Julia 100.00%

bibliography bibtex-citations julia documentation

documentercitations.jl's Introduction

I'm an Applied Scientist at Afresh working on reducing food waste, a huge contributor to climate change, by using machine learning to help grocery stores optimize their inventory management and ordering decisions.

Before that I received my PhD in Computational Earth, Atmospheric, and Planetary Sciences from MIT where I worked at the intersection of climate science and scientific machine learning. As part of the Climate Modeling Alliance I developed Oceananigans.jl, a fast and flexible next-generation ocean model written in Julia that runs on GPUs, and used it to train machine learning models of geophysical turbulence and simulate all kinds of fluid dynamics.

And before that I received my MS and BS in Physics from the University of Waterloo where I used ultrashort pulse lasers and synchrotrons to make movies of molecular dynamics.

You can find out more about me and read my blog/ramblings on my personal website: http://aliramadhan.me/

documentercitations.jl's People

Contributors

Stargazers

Watchers

Forkers

simonbyrne simonmandlik timknab fingolfin hesamshaelaie vchuravy mloubout hofsmo jldc glwagner

documentercitations.jl's Issues

Integration testing

I would suggest running a few small documentation builds as integration tests. We do that in Documenter's own tests.

Originally posted by @mortenpi in #4 (comment)

Allow arbitrary link texts

Just like Documenter.jl in general supports arbitrary link texts with the syntax [Custom Header](@ref my_custom_header_name), DocumenterCitations.jl should support the syntax [text](@cite key), which simply renders as text.

Especially in docstrings I would often want to include a "manual" list of references, e.g.

# Reference

* [Mayer, Krechetnikov, Phys. Rev. E 85, 046117 (2012)](@cite Mayer2012)

which may also be the underlying motivation of #62. The generalized syntax might also partially address #15 and #32.

Docs compilation error

When trying to compile the documentation (numericalshadow/numericalshadow.org@90c5d5c) I get an error

ERROR: LoadError: MethodError: no method matching header_level(::BibInternal.Entry)
Closest candidates are:
  header_level(::Markdown.Header{N}) where N at /home/lpawela/.julia/packages/Documenter/WSKVc/src/Utilities/Utilities.jl:315
Stacktrace:
 [1] populate!(::Documenter.Documents.ContentsNode, ::Documenter.Documents.Document) at /home/lpawela/.julia/packages/Documenter/WSKVc/src/Documents.jl:428
 [2] populate!(::Documenter.Documents.Document) at /home/lpawela/.julia/packages/Documenter/WSKVc/src/Documents.jl:390
 [3] runner(::Type{Documenter.Builder.Populate}, ::Documenter.Documents.Document) at /home/lpawela/.julia/packages/Documenter/WSKVc/src/Builder.jl:235
 [4] dispatch(::Type{Documenter.Builder.DocumentPipeline}, ::Documenter.Documents.Document) at /home/lpawela/.julia/packages/Documenter/WSKVc/src/Utilities/Selectors.jl:167
 [5] #2 at /home/lpawela/.julia/packages/Documenter/WSKVc/src/Documenter.jl:240 [inlined]
 [6] cd(::Documenter.var"#2#3"{Documenter.Documents.Document}, ::String) at ./file.jl:104
 [7] #makedocs#1 at /home/lpawela/.julia/packages/Documenter/WSKVc/src/Documenter.jl:239 [inlined]
 [8] top-level scope at /home/lpawela/new-zksi-repo/numericalshadow.org/make.jl:95
 [9] include(::Function, ::Module, ::String) at ./Base.jl:380
 [10] include(::Module, ::String) at ./Base.jl:368
 [11] exec_options(::Base.JLOptions) at ./client.jl:296
 [12] _start() at ./client.jl:506
in expression starting at /home/lpawela/new-zksi-repo/numericalshadow.org/make.jl:95

Without DocumenterCitations everwything works. Am I doing something wrong?

Allow citation of specific pages or information.

Not sure how to implement this yet but would be neat if we could cite specific pages, e.g. [useful_book](@cite, pp. 101--105).

Define both `@citet` and `@citep`?

I'm a big fan of Natbib's citet and citep commands, i.e. the difference between citing Someone (2020) and (Someone, 2020).

Shouldn't be hard to implement both. And @cite should probably default to citep (?) even though natbib defaults it to citet I think.

Option to print last name only for citations

Would it be possible to add a global option so that citations only give the last name of the authors, not their first names? E.g. "Knuth (2011)" instead of "Donald E. Knuth (2011)".

Bibliography for page

I would like to have a bibliography for a page with the references used only on that page. For instance here https://lpawela.github.io/numericalshadow.org/dev/numerical-shadow/ only few references are used (currently wrongly displayed due to #24 ) and I would like only these works displayed in the References section.

Convert TeX umlauts and accents also in `@ref` commands, not just the bibliography

On https://oscar-system.github.io/Oscar.jl/dev/references/ the umlaut character like ö and ü appear just fine. E.g. the final entry is

Günter M. Ziegler, Lectures on polytopes, Springer-Verlag, New York, 1995.

But when they are cited, this is not the case, see e.g. https://oscar-system.github.io/Oscar.jl/dev/PolyhedralGeometry/pg/ where [Zie95](@cite) is rendered as:

G"{u}nter M. Ziegler (1995)

But ideally it would appear as

Günter M. Ziegler (1995)

Some documentation

It's just a Documenter.jl plugin so maybe we don't need to set up full docs to show how to use it? Maybe just some quick info the README should be enough to start with?

Change `CitationBibliography` to `DocumenterBibliography`?

@charleskawczynski What do you think of changing CitationBibliography to DocumenterBibliography?

CitationBibliography sounds somewhat redundant while DocumenterBibliography might be a bit more descriptive.

Configure CI

Switch to GitHub Actions

@charleskawczynski suggested it would make push previews much easier to access which is a big reason since we'll probably be using push previews to debug quite a bit.

TagBot trigger issue

This issue is used to trigger TagBot; feel free to unsubscribe.

If you haven't already, you should update your TagBot.yml to include issue comment triggers.
Please see this post on Discourse for instructions and more details.

If you'd like for me to do this for you, comment TagBot fix on this issue.
I'll open a PR within a few hours, please be patient!

Testing new bibtex parser

Hi @ali-ramadhan ,

I have been changing a few things in BibParser.jl and Bibliography.jl. The syntax is the same as before, but you might see some changes (it should be improvements) here.

Could you check? Version of Bibliography.jl should be v0.2.1.

Year is printed twice

Looking at http://aliramadhan.me/DocumenterCitations.jl/dev/references/ the years are printed twice (after the names and at the very end). That's strange. It also happens in our docs (where I noticed it first).

Mayer2012
H. C. Mayer , R. Krechetnikov (2012), Walking with coffee: {Why} does it spill?, Physical Review E, 85, 046117, 2012

Sorting of bibliography entries

Can they be sorted by author-year?

c.f. CliMA/ClimateMachine.jl#1687 (comment)

Support for custom citation and bibliography styles

Would be useful to be able to customize how the citation and bibliographies are printed.

Math mode data gets mangled

Right now we have this:

julia> DocumenterCitations.tex2unicode(raw"{$\overline{M}$}")
"{\$\\overlineM\$}"

But that's not right, it shouldn't strip those inner braces, as the result is invalid LaTeX and won't be rendered right.

This is caused by the following rule, I believe:

r"\{([[:alnum:]]+)\}" => s"\1",  # {<text>} 	<text> 	bracket stripping after applying all rules

Frankly I don't understand the purpose of this rule. Besides clearly being incorrect (in the sense that it changes semantics of the code, as seen in my example), it is quite unclear to me why one would want to do that, i.e. what the purpose of this substitution is? It was introduced by @LazyScholar in PR #49 but no explanation was given there.

Volume should be an optional field for article

For the bibtex info

@article{white1982maximum,
  title={Maximum likelihood estimation of misspecified models},
  author={White, Halbert},
  journal={Econometrica: Journal of the Econometric Society},
  pages={1--25},
  year={1982},
  publisher={JSTOR}
}

I'm getting

ERROR: LoadError: Entry white1982maximum is missing the volume field(s).

but volume is an optional field, see https://www.bibtex.com/e/article-entry/.

When using `doctest=:fix`, I get `ERROR: KeyError: key Markdown.Code(...`

When trying to "fix" doctests for our project, I get the following error in Julia 1.6.5, with Documenter v0.27.10 and DocumenterCitations v0.2.11 and also DEV

julia> Documenter.doctest(Oscar; fix=true)
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
┌ Warning: could not find code block in source file
└ @ Documenter.DocTests ~/.julia/packages/Documenter/qdbx6/src/DocTests.jl:421
[ Info: Skipped ExpandTemplates step (doctest only).
[ Info: Skipped CrossReferences step (doctest only).
[ Info: Citations: building citations.
┌ Error: Doctesting failed
│   exception =
│    KeyError: key Markdown.Code("@meta", "CurrentModule = Oscar\nDocTestSetup = quote\n  using Oscar\nend") not found
│    Stacktrace:
│      [1] getindex(d::IdDict{Any, Any}, key::Any)
│        @ Base ./iddict.jl:93
│      [2] expand_citations(doc::Documenter.Documents.Document)
│        @ DocumenterCitations ~/.julia/packages/DocumenterCitations/syRlI/src/citations.jl:15
│      [3] runner(#unused#::Type{DocumenterCitations.Citations}, doc::Documenter.Documents.Document)
│        @ DocumenterCitations ~/.julia/packages/DocumenterCitations/syRlI/src/citations.jl:8
│      [4] dispatch(#unused#::Type{Documenter.Builder.DocumentPipeline}, x::Documenter.Documents.Document)
│        @ Documenter.Utilities.Selectors ~/.julia/packages/Documenter/qdbx6/src/Utilities/Selectors.jl:170
│      [5] #2
│        @ ~/.julia/packages/Documenter/qdbx6/src/Documenter.jl:266 [inlined]
│      [6] cd(f::Documenter.var"#2#3"{Documenter.Documents.Document}, dir::String)
│        @ Base.Filesystem ./file.jl:106
│      [7] makedocs(; debug::Bool, format::Documenter.Writers.HTMLWriter.HTML, kwargs::Base.Iterators.Pairs{Symbol, Any, NTuple{6, Symbol}, NamedTuple{(:root, :source, :sitename, :doctest, :modules, :doctestfilters), Tuple{String, String, String, Symbol, Vector{Module}, Vector{Regex}}}})
│        @ Documenter ~/.julia/packages/Documenter/qdbx6/src/Documenter.jl:265
│      [8] (::Documenter.var"#all_doctests#32"{Bool, Vector{Regex}, Vector{Module}})()
│        @ Documenter ~/.julia/packages/Documenter/qdbx6/src/Documenter.jl:874
│      [9] macro expansion
│        @ ~/.julia/packages/Documenter/qdbx6/src/Documenter.jl:895 [inlined]
│     [10] macro expansion
│        @ /Users/julia/buildbot/worker/package_macos64/build/usr/share/julia/stdlib/v1.6/Test/src/Test.jl:1151 [inlined]
│     [11] doctest(source::String, modules::Vector{Module}; fix::Bool, testset::String, doctestfilters::Vector{Regex})
│        @ Documenter ~/.julia/packages/Documenter/qdbx6/src/Documenter.jl:895
│     [12] doctest(package::Module; manual::Bool, testset::Nothing, kwargs::Base.Iterators.Pairs{Symbol, Bool, Tuple{Symbol}, NamedTuple{(:fix,), Tuple{Bool}}})
│        @ Documenter ~/.julia/packages/Documenter/qdbx6/src/Documenter.jl:830
│     [13] top-level scope
│        @ REPL[59]:1
│     [14] eval
│        @ ./boot.jl:360 [inlined]
│     [15] eval_user_input(ast::Any, backend::REPL.REPLBackend)
│        @ REPL /Users/julia/buildbot/worker/package_macos64/build/usr/share/julia/stdlib/v1.6/REPL/src/REPL.jl:139
│     [16] repl_backend_loop(backend::REPL.REPLBackend)
│        @ REPL /Users/julia/buildbot/worker/package_macos64/build/usr/share/julia/stdlib/v1.6/REPL/src/REPL.jl:200
│     [17] start_repl_backend(backend::REPL.REPLBackend, consumer::Any)
│        @ REPL /Users/julia/buildbot/worker/package_macos64/build/usr/share/julia/stdlib/v1.6/REPL/src/REPL.jl:185
│     [18] run_repl(repl::REPL.AbstractREPL, consumer::Any; backend_on_current_task::Bool)
│        @ REPL /Users/julia/buildbot/worker/package_macos64/build/usr/share/julia/stdlib/v1.6/REPL/src/REPL.jl:317
│     [19] run_repl(repl::REPL.AbstractREPL, consumer::Any)
│        @ REPL /Users/julia/buildbot/worker/package_macos64/build/usr/share/julia/stdlib/v1.6/REPL/src/REPL.jl:305
│     [20] (::Base.var"#875#877"{Bool, Bool, Bool})(REPL::Module)
│        @ Base ./client.jl:387
│     [21] #invokelatest#2
│        @ ./essentials.jl:708 [inlined]
│     [22] invokelatest
│        @ ./essentials.jl:706 [inlined]
│     [23] run_main_repl(interactive::Bool, quiet::Bool, banner::Bool, history_file::Bool, color_set::Bool)
│        @ Base ./client.jl:372
│     [24] exec_options(opts::Base.JLOptions)
│        @ Base ./client.jl:302
│     [25] _start()
│        @ Base ./client.jl:485
└ @ Documenter ~/.julia/packages/Documenter/qdbx6/src/Documenter.jl:884

Replace (@cite) in REPL help mode.

Markdown links [some text](URL) get displayed as hyperlinks in the created document (HTML) but in text-based outputs like the REPL help (?) mode it gets substituted by some text (URL). Similarly (@ref)s get deleted. It would be nice to have something similar and either remove the (@cite) or format it some other way.

Edition missing

The edition field of a Bibtex entry seems to be missing from the generated references. Could this be added?

Here's an example:

@book{Knuth-4A,
	author = {Knuth, D. E.},
	edition = {Sixteenth printing, April 2021},
	pages = {xv+883},
	publisher = {Addison-Wesley, Upper Saddle River, NJ},
	title = {The art of computer programming. {V}ol. 4{A}. {C}ombinatorial algorithms. {P}art 1},
	year = {2011}}

I've had some troubles understanding a build break, and found out that when using

  ```@contents
  Pages = ["references.md"]```

or less carefully

  ```@contents```

results in a documentation build break

 ~/.julia/dev/DocumenterCitations.jl !master 

$ julia docs/make.jl
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: Expanding bibliography.
[ Info: Expanding bibliography entry: useful_proof.
[ Info: Expanding bibliography entry: CK1994.
[ Info: Expanding bibliography entry: Heun1900.
[ Info: Expanding bibliography entry: Mayer2012.
[ Info: CrossReferences: building cross-references.
[ Info: Citations: building citations.
[ Info: Expanding citation: Mayer2012.
[ Info: Expanding citation: useful_proof.
[ Info: Expanding citation: Heun1900.
[ Info: Expanding citation: Mayer2012.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
ERROR: LoadError: MethodError: no method matching header_level(::BibInternal.Entry)
Closest candidates are:
  header_level(::Markdown.Header{N}) where N at /Users/user/.julia/packages/Documenter/6vUwN/src/Utilities/Utilities.jl:315
Stacktrace:
 [1] populate!(::Documenter.Documents.ContentsNode, ::Documenter.Documents.Document) at /Users/user/.julia/packages/Documenter/6vUwN/src/Documents.jl:428
 [2] populate!(::Documenter.Documents.Document) at /Users/user/.julia/packages/Documenter/6vUwN/src/Documents.jl:390
 [3] runner(::Type{Documenter.Builder.Populate}, ::Documenter.Documents.Document) at /Users/user/.julia/packages/Documenter/6vUwN/src/Builder.jl:248
 [4] dispatch(::Type{Documenter.Builder.DocumentPipeline}, ::Documenter.Documents.Document) at /Users/user/.julia/packages/Documenter/6vUwN/src/Utilities/Selectors.jl:170
 [5] #2 at /Users/user/.julia/packages/Documenter/6vUwN/src/Documenter.jl:247 [inlined]
 [6] cd(::Documenter.var"#2#3"{Documenter.Documents.Document}, ::String) at ./file.jl:104
 [7] #makedocs#1 at /Users/user/.julia/packages/Documenter/6vUwN/src/Documenter.jl:246 [inlined]
 [8] top-level scope at /Users/user/.julia/dev/DocumenterCitations.jl/docs/make.jl:6
 [9] include(::Function, ::Module, ::String) at ./Base.jl:380
 [10] include(::Module, ::String) at ./Base.jl:368
 [11] exec_options(::Base.JLOptions) at ./client.jl:296
 [12] _start() at ./client.jl:506
in expression starting at /Users/user/.julia/dev/DocumenterCitations.jl/docs/make.jl:6