Introduction
Besides writing and running tests, another pillar of good programming practices is creating documentation.
Documentation is too important to be ignored. From a user’s perspective, undocumented features simply do not exist. And from the perspective of collaborators or even our own future-selves, documentation can provide a guide to the features which are actually working, as well as a roadmap for future development plans.
With the tools provided by Julia, the mechanics of creating documentation amount to little more than adding certain type of well-formatted comments to your code. So this leaves little room for excuses regarding the inconveniance of writing (and mantaining) documentation of our projects.
Create Docstrings from Code Comments
Comments preceding the definition of a function are called docstrings
. These docstrings are typed using Julia’s Markdown Syntax, and will be parsed automatically in various situations.
For example, let’s add the following docstrings
to our test project (MyProject.jl), which include some Latex elements:
"Simple dummy project module to demonstrate how a project can be organized."
module MyProject
export ArithmeticSum
"""
ArithmeticSum(a₁,Δ,n)
Returns the sum of the arithmetic sequence starting from a₁,
with interval Δ and n terms. In other words, given
``a_i = a_1 + (i-1)$Delta`` the following sum is computed:
``` math
s = a_1 + a_2 + a_3 + $dots + a_n
```
"""
ArithmeticSum(a₁,Δ,n) = return (n+1)*(a₁ + (a₁+n*Δ))/2
end
Once you have done this, when you begin using
your project, you’ll be able to access the docstrings from the REPL.
using MyProject
?MyProject
?ArithmeticSum
Building the HTML Documentation
Now move back, and create an /docs/src/index.md
file, with the following content:
# This is MyProject Documentation
Welcome to the documentation page.
!!! note "Quick-Glimpse Tutorial"
This tutorial just offered a quick glimpse on Julia's built-in documentation system, make sure to read the docs for more.
```@docs
MyProject
ArithmeticSum(a₁,Δ,n)
```
To generate the HTML documentation, you will also need a docs/make.jl
file, with the following:
using Documenter, MyProject
makedocs(sitename="MyProject")
Now, simply run from a bash shell (in this case from the top-level folder) the following command:
julia --project=. docs/make.jl
Further Reading
For advance use of Documenter.jl, Documenter.jl Feature Showcase is an excellent resource, as well as Julia’s Docs on Documentation.