Automated Documentation

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.