Julia's equivalents to R's help pages and vignettes?

user_5851905 0
Viewed 142

Coming from an R background, and just started learning Julia, I wonder how's documentation in Julia, and if there are analogues to R's help pages and vignettes.

Furthermore, in R, one can document functions using roxygen comment blocks, is there also something similar in Julia?

julia
1 Answers

I think it is best to understand how things work by example. I will comment on how DataFrames.jl is documented as this is a pretty standard approach:

  1. Functions are documented using docstrings, here is an example of a docstring of function names; These docstrings are then discoverable interactively via help system (by pressing ?)
  2. A standard way to generate a documentation for a package is to use Documenter.jl; by the way: the package has a great team of maintainers who are very helpful and responsive; here you have a link to the make.jl file that is executed to generate the documentation; note in particular the option doctest=true which makes sure that all code examples that are properly anoteted following Documenter.jl rules are producing an expected output
  3. In order to set-up auto-generation of package documentation you need to set up CI integration on GitHub; again - there are many ways to do it; a standard one is to use GitHub Actions; here you have a link to the part of the ci.yml specification file that ensures that documentation is built as a part of CI; then in any PR, e.g. this one (I am giving a link to a currently open PR that is documentation related) you can see in the section reporting CI results that after running tests also documentation was generated. Here you can see how a documentation generated using this toolchain looks like (e.g. note that at the bottom you can switch the version of the package you want to read manual of dynamically which shows you that all here is really well integrated - not just a bunch of PDF or HTML files).

I hope this will help you to get started. I have pointed you to all essential pieces that are normally used by packages hosted on GitHub (i.e. this is not the only way to do it, but it is a standard way most commonly used).

To master all the details of the above you need to read the documentation in the Julia Manual and Documenter.jl carefully. Unfortunately writing a proper documentation is not easy (in any programming language). The good thing is that Julia has a really excellent toolchain that supports this process very well.

user_12695670
Related