# Citations in docs

**URL:** <https://discourse.julialang.org/t/citations-in-docs/5066>\
**Category:** General Usage\
**Created:** [July 25, 2017, 7:46pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066 "2017-07-25T19:46:50Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![jacobcvt12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobcvt12/32/2695_2.png) [@jacobcvt12](https://discourse.julialang.org/u/jacobcvt12)\
**Post date:** [July 25, 2017, 7:46pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/1 "2017-07-25T19:46:50Z")

</div>

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

```julia
"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`?

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [July 26, 2017, 3:25pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/2 "2017-07-26T15:25:36Z")

</div>

> [@jacobcvt12](#):
>
> Is it possible to have bibtex references in your docs?

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

---

<div class="post-metadata">

**Author:** ![jacobcvt12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobcvt12/32/2695_2.png) [@jacobcvt12](https://discourse.julialang.org/u/jacobcvt12)\
**Post date:** [July 26, 2017, 4:29pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/3 "2017-07-26T16:29:35Z")

</div>

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

```julia-auto
module GLM

export glm

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

end

```

and `src/model.jl` looks like

```julia-auto
"""
    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?

---

<div class="post-metadata">

**Author:** ![bramtayl](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bramtayl/32/3614_2.png) [@bramtayl](https://discourse.julialang.org/u/bramtayl)\
**Post date:** [July 26, 2017, 5:30pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/4 "2017-07-26T17:30:56Z")

</div>

Seems like something Documenter could do, perhaps via pandoc.

---

<div class="post-metadata">

**Author:** ![bramtayl](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bramtayl/32/3614_2.png) [@bramtayl](https://discourse.julialang.org/u/bramtayl)\
**Post date:** [July 26, 2017, 5:31pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/5 "2017-07-26T17:31:29Z")

</div>

Note that citations should be working in Weave.jl

---

<div class="post-metadata">

**Author:** ![ChrisRackauckas](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/chrisrackauckas/32/77_2.png) [@ChrisRackauckas](https://discourse.julialang.org/u/ChrisRackauckas)\
**Post date:** [July 26, 2017, 6:57pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/6 "2017-07-26T18:57:52Z")

</div>

> [@bramtayl](#):
>
> Seems like something Documenter could do, perhaps via pandoc.

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

---

<div class="post-metadata">

**Author:** ![bramtayl](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bramtayl/32/3614_2.png) [@bramtayl](https://discourse.julialang.org/u/bramtayl)\
**Post date:** [July 26, 2017, 7:06pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/7 "2017-07-26T19:06:35Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![ChrisRackauckas](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/chrisrackauckas/32/77_2.png) [@ChrisRackauckas](https://discourse.julialang.org/u/ChrisRackauckas)\
**Post date:** [July 26, 2017, 7:12pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/8 "2017-07-26T19:12:00Z")

</div>

> [@bramtayl](#):
>
> Wait I must have missed something. You mean there were problems with pandoc, or Documenter?

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

> <https://github.com/JuliaLang/www_old.julialang.org/issues/421>
>
> The instructions \[here\](https://github.com/JuliaLang/julialang.github.com/blob/m…aster/publications/README.md) require installing pandoc, Jekyll and a bunch of other stuff. This is a pretty annoyingly high bar and we should make this less onerous – we do want people to submit publications, right? Directly editing markdown and bib files should be sufficient.

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.

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [July 26, 2017, 7:16pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/9 "2017-07-26T19:16:01Z")

</div>

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).

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [July 26, 2017, 7:31pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/10 "2017-07-26T19:31:57Z")

</div>

> [@stevengj](#):
>
> write a bibTeX parser in Julia

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](https://github.com/ptigas/bibpy/blob/master/bibpy/bib.py)

---

<div class="post-metadata">

**Author:** ![jacobcvt12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobcvt12/32/2695_2.png) [@jacobcvt12](https://discourse.julialang.org/u/jacobcvt12)\
**Post date:** [July 26, 2017, 7:52pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/11 "2017-07-26T19:52:27Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![bramtayl](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bramtayl/32/3614_2.png) [@bramtayl](https://discourse.julialang.org/u/bramtayl)\
**Post date:** [July 26, 2017, 8:11pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/12 "2017-07-26T20:11:25Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Ken-B](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ken-b/32/1780_2.png) [@Ken-B](https://discourse.julialang.org/u/Ken-B)\
**Post date:** [July 26, 2017, 10:06pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/13 "2017-07-26T22:06:13Z")

</div>

For reference, @lucianolorenti already [investigated](https://github.com/JuliaDocs/Documenter.jl/issues/379#issuecomment-292157714) this approach a few months ago with some promising results.

---

<div class="post-metadata">

**Author:** ![jacobcvt12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobcvt12/32/2695_2.png) [@jacobcvt12](https://discourse.julialang.org/u/jacobcvt12)\
**Post date:** [July 27, 2017, 2:13pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/14 "2017-07-27T14:13:19Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![jacobcvt12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobcvt12/32/2695_2.png) [@jacobcvt12](https://discourse.julialang.org/u/jacobcvt12)\
**Post date:** [July 27, 2017, 2:23pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/15 "2017-07-27T14:23:54Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [July 27, 2017, 7:13pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/16 "2017-07-27T19:13:35Z")

</div>

> [@jacobcvt12](#):
>
> Just thinking out loud, but if something like I suggested were wanted, would we need a bibtex parser in Julia?

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.

---

<div class="post-metadata">

**Author:** ![jacobcvt12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobcvt12/32/2695_2.png) [@jacobcvt12](https://discourse.julialang.org/u/jacobcvt12)\
**Post date:** [July 27, 2017, 8:07pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/17 "2017-07-27T20:07:07Z")

</div>

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

[https://github.com/jacobcvt12/bib.jl](https://github.com/jacobcvt12/bib.jl)

Hope to have a working version some time next week.

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [July 28, 2017, 6:28am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/18 "2017-07-28T06:28:56Z")

</div>

Splicing the references into docstrings could be something for [DocStringExtensions](https://github.com/JuliaDocs/DocStringExtensions.jl). I’d be happy to review a PR for this.

---

<div class="post-metadata">

**Author:** ![bramtayl](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bramtayl/32/3614_2.png) [@bramtayl](https://discourse.julialang.org/u/bramtayl)\
**Post date:** [July 30, 2017, 6:05pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/19 "2017-07-30T18:05:00Z")

</div>

I’ve got a parser up [here](https://github.com/bramtayl/BibTeX.jl)

---

<div class="post-metadata">

**Author:** ![jacobcvt12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobcvt12/32/2695_2.png) [@jacobcvt12](https://discourse.julialang.org/u/jacobcvt12)\
**Post date:** [July 31, 2017, 2:31pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/20 "2017-07-31T14:31:34Z")

</div>

@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](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html). 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?

[Next page](https://discourse.julialang.org/t/citations-in-docs/5066.md?page=2)