Citations in docs

General Usage
1

Is it possible to have bibtex references in your docs? something along the lines of

"Computes a p-value that can never be misinterepreted [@fisher]"
function pvalue()
    ...
end

That will then be replaced with both an inline citation and full citation at the bottom when the user views the help for pvalue?

9 Likes
2

I don’t think anything like this is currently implemented, but it is an interesting idea.

1 Like
3

Thanks @stevengj. I’m not sure how this could be implemented, but something like this would be nice.

Suppose one goes to author a package to implement GLMs. He/she has a references.bib in the package, and his/her src/GLM.jl might look like

module GLM

export glm

include("model.jl")
bib("references.bib")

end

and src/model.jl looks like

"""
    glm(formula, data)

Estimates parameter for generalized linear model [@mccullagh1989].
"""
function glm(formula, data)
    ...
end

Which in help would appear roughly as

glm(formula, data)

Estimates parameter for generalized linear model (McCullagh and Nelder 1989).

References

McCullagh P. and Nelder, J. A. (1989) Generalized Linear Models. London: Chapman and Hall.

Would something like this have to be implemented in the core of Julia? Or do you think it would be possible to do in a package?

1 Like
4

Seems like something Documenter could do, perhaps via pandoc.

5

Note that citations should be working in Weave.jl

6

Oh god, not again. We just got that off the JuliaLang website. There must be something easier.

7

Wait I must have missed something. You mean there were problems with pandoc, or Documenter?

8

Pandoc. The pandoc + Jekyll combination was used for JuliaLang citations.

There must be an easier way than requiring everyone has pandoc appropriately installed and working. With the HTML render, Documenter.jl is pure Julia, so I’d like to find a way to keep it that way because the fact that everything auto-installs without any extra pieces makes it much easier to use.

1 Like
9

Seems like it wouldn’t be too hard to write a bibTeX parser in Julia, and something to generate citations in a single “Julia” format (rather than trying to handle zillions of possible citation styles like Jekyll-Scholar).

2 Likes
10

Here’s one in Python (MIT/expat licensed, so okay to translate) that’s about 250 lines: https://github.com/ptigas/bibpy/blob/master/bibpy/bib.py

2 Likes
11

Thanks for the ideas. @bramtayl is it possible to “modify” the help docstring with Documenter? I’m still learning about documentation within Julia, but it seems like Documenter is used to generate HTML documents.

@stevengj agreed - you really only need one single format for this type of citation.

12

No I guess not. I was thinking you could use documenter + pandoc to render citations + a bibliography in html. This would show up if your package had a documentation website. But it sounds like a bad idea based on the above.

13

For reference, @lucianolorenti already investigated this approach a few months ago with some promising results.

14

Thanks @Ken-B. Interested to see what comes of this.

15

Just thinking out loud, but if something like I suggested were wanted, would we need a bibtex parser in Julia?

16

Yes. If we wanted a citation system in a very basic component like Documenter.jl, much less in the built-in Markdown parser, I don’t think it we would want it to have a heavyweight dependency like Python or Pandoc, and bibtex is a pretty reasonable standard format to adopt for citation input. Fortunately, something like bibpy looks pretty easy to port to Julia.

3 Likes
17

Gotcha. Agreed, seems pretty easy to port. I started a package here.

https://github.com/jacobcvt12/bib.jl

Hope to have a working version some time next week.

3 Likes
18

Splicing the references into docstrings could be something for DocStringExtensions. I’d be happy to review a PR for this.

19

I’ve got a parser up here

20

@mortenpi, now that @bramtayl has a working bibtex parser, what should the process be for splicing references into docstrings?

Also, per @stevengj, we should probably settle on a single citation style. Personally, I am a fan of how rmarkdown handles citations. Their process allows inclusion of inline author/date citations (or just date, sans author, if you already mention the author in the sentence). The style defaults to chicago.

Thoughts?