Tutorials
Blog
About

Tutorials > Julia Programming: a Hands-on Tutorial

Automated Documentation

by Martin D. Maas, Ph.D
@MartinDMaas

Last updated: 2021-11-16

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 to the /docs/src/index.md and replace it with the following:

# 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, simply run from a bash shell (in this case from the top-level folder) the following command:

julia --project=. docs/make.jl

Doc

Further Reading

For advance use of Documenter.jl, Documenter.jl Feature Showcase is an excellent resource, as well as Julia’s Docs on Documentation.

Don't miss any updates!

I'm writing a newsletter about once a month, with links to new posts and tutorials.

In particular, one of my goals for 2022 is to write a book about scientific software development using Julia. Make sure to subscribe if you are interested!