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