7. Documenting your Module

To display the documentation of your project to the public, you have several options, amongst others:

  • Use the README.md file.
  • Create the documentation with the Julia package Documenter.jl.

You write the documentation in markdown language.

The Julia package Documenter.jl creates HTML-pages based on the Julia Markdown language. See also the Documenter.jl Style Guide for guidelines.

If you have a GitHub website, then the documentation becomes visible when you push the data to GitHub. An example is documentation for the AppliGeneralLedger package we use in this course.

You can set up a website by creating a repository with the name <your username>.gitub.io and enable it for GitHub Pages and push your pages written in markdown language to GitHub.


Activity 7.1 - Initialize the File Structure for the Documentation

Before you write the documentation you have to set up the file structure.


In this activity you will:

  1. Create the git branch.
  2. Add the Documenter.jl and DocumenterTools.jl packages.
  3. Create the file structure for your documentation.

Step 1: Create the Git Branch.

When you want to add new features to a project it is common to create a Git branch. This gives you the freedom to write and test your code without disturbing the current code. You finish your work by merging it into the main branch. In this step, you create the branch docs.

1$ cd ~/.julia/dev/AccountsOr make a clone of Accounts with git clone https://github.com/rbontekoe/Accounts.jl.git.
2$ git branch docsCreate a new branch.
3$ git checkout docsMake the docs branch active.
4$ code .Start VSCode.
5Ctrl+Shift-PShow All Commands.
6Select: Julia: start REPLStart Julia REPL. The code will be recompiled.
Step 2: Add the Documenter and DocumenterTools Packages.

Documentation for GitHub is more or less standardized when you want to use GitHub Pages. To assist you, you can use the Julia packages Documenter.jl and DocumenterTools.jl.

1julia> ]Start the package manager.
2pkg> add DocumenterAdd the Documenter.jl package. It is installed in the general repository, so we can use it always.
3pkg> add DocumenterToolsAdd the tool to generate the basic file structure
4Press: <BackSpace>Return to Julia.
Step 3: Create the File Structure.

The Julia package DocumenterTools.jl creates the folder docs in your project and the necessary folders and files.

1julia> using DocumenterLoad the Documenter package.
2julia> using DocumenterToolsLoad the DocumenterTools package.
3julia> DocumenterTools.generate(name="Accounts")Create the basic file structure.
แตฅ๐Ÿ“ Accounts
  แตฅ๐Ÿ“ docs #1
    แตฅ๐Ÿ“ src #2
       ๐Ÿ“„ index.md #3
     ๐Ÿ“„ .gitignore #4
     ๐Ÿ“„ make.jl #5
     ๐Ÿ“„ Project.toml #6

#1 DocumenterTools creates a sub-folder doc.

#2 src is one of the two sub-folders within docs. The other one is build that will be created when you run make.jl.

#3 index.md is the markdown file for the home-page of the documentation.

#4 .gitignore contains the files that will not be uploaded to GitHub. It contains the build-folder.

#5 make.jl is the Julia program that converts the markdown to HTML-files. The files are put in the build-folder.

#6 Since Julia version 1.2 you can specify dependencies used by Documenter in Project.jl. (A similar situation applies to the test-folder.)

Activity 7.2 - Create the API page

You start with building the markdown file for the API method create. Later on in this chapter, you will create the documentation for the Infrastructure methods plus an extra markdown file for an Example.


In this activity you will:

  1. Modify the home page.
  2. Create the file api.md.
Step 1: Modify the home page.
1Open index.mdUnder the folder docs/src
2Type on line 3: Documentation of Accounts.jl
3Save the file: Ctrl-S
Step 2: Create the file api.md.
1Select: src
2Right click and select: New File
3Type: api.md
4Save the file: <Enter>Press the Enter-button to create the file.
5Paste the following code into the file:
# 1. API

## create
7Save the file: Ctrl-S


using Documenter
using Accounts
using Dates

        "Accounts" => "index.md",
        "1 - API" => "api.md",
        #"2 - Infrastructure" => "infrastructure.md",
        #"3 - Example" => "example.jl"

Activity 7.3 - Create the documentation

You create the documentation with the aid of the Julia code in the file make.jl. The code creates HTML-files from the markdown files in the folder docs/build.


In this activity you will:

  1. Modify the file make.jl.
  2. Run the code in the file make.jl.
  3. Display the generated documentation in the browser.
  4. Copy the HTML-Code to the Folders stable and dev

Step 1: Modify the File make.jl.

In make.jl, you define, among others, the structure of the pages for the sidebar. Otherwise, Documenter.jl displays the pages in alphabetic order of the .md files.

1Open the file make.jl
2Replace the code in the code from section make.jl
3Ctrl-SSave the file.
Step 2: Run the Code in the File make.jl.

It is time to create the HTML-files.

1Close VSCode
2$ code .Start VSCode
3Click in the REPL panel
4julia> ]Activate the package manager.
5Pkg> activate .Activate current folder.
6<BackSpace>Return to Julia.
7In the Explorer panel, right-click on: make.jl
8Select: Julia: Execute FileThe following messages appear in the REPL pane:
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
Step 3: Display the Generated Documentation in the Browser.

The code in make.jl creates HTML folders and files in docs/build. You can look at the result in your browser.

1Open your browser
2Ctrl-OBrowser command to open a HTML-file.
3Select: Home > .julia > dev > Accounts > docs > build > index.htmlOpen index.html.
Step 4: Copy the HTML-Code to the Folders stable and dev.

Often you see the documentation split into stable and dev. As long as you are working on new features, you want to show it only to people who are interested in it. And that is why the documentation you put into the dev-folder. When you merge the dev into the main branch, then you copy it into the stable-folder.

1Go to the terminal where you started VSCode~/.jula/dec/Accounts
2Go to the docs folder
3Execute the following commands:
mkdir dev

mkdir stable

cd dev

cp -r ../build/* .

cd ../stable

cp -r ../build/* .
4Go to your browser
6Select: Home > .julia > dev > Accounts > docs > dev > index.html

Exercise 7.1: Show the Documentation on the Web.

When you have a GitHub website you can show the documentation on the web.


  • GitHub website: https://<your name>/github.io/


  • Update Accounts on GitHub.
  • Activate pages for Accounts: Settings > GitHub Pages.
  • Select master in Select branch.
  • Select folder: /docs.
  • Click on the Save-button.
  • Display the documentation in the browser: https://<your name>/github.io/Accounts/stable

Exercise 7.2: Add Docstrings to the Infrastructure Methods



  • Exercise 7.1


  • Paste the following Docstring just above the method add_to_file in Infrastructure.jl.

Store persons in the datastore.

# Example
julia> using Accounts

julia> const FILE_ACCOUNTS = "./test_accounts.txt";

julia> address_email = create(EMAIL, "donald@duckcity.com");

julia> donald = create("Donald Duck", [address_email]);

julia> add_to_file(FILE_ACCOUNTS, [donald])
  • Paste the following Docstring just above the method read_from_file in Infrastructure.jl.

Get persons from the datastore.

# Example
julia> using Accounts

julia> const FILE_ACCOUNTS = "./test_accounts.txt";

julia> address_email = create(EMAIL, "donald@duckcity.com");

julia> donald = create("Donald Duck", [address_email]);

julia> add_to_file(FILE_ACCOUNTS, [donald])

julia> read_from_file(FILE_ACCOUNTS)
1-element Array{Any,1}:
 Accounts.Domain.Person("10973269859630729578", DateTime("2020-09-28T10:41:17.59"), "Donald Duck", Accounts.Domain.Address[Accounts.Domain.Address("6678746402434096981", DateTime("2020-09-28T10:41:17.277"), EMAIL, "donald@duckcity.com")])
  • Create the file Infrastructure.md.
  • Add the following code to the file:
# Infrastructure

## add\_to\_file

## read\_from\_file
  • Run make.jl.
  • Inspect the result in your browser.


You can create documentation for your application by using Documenter.jl. The documentation is written in markdown language. The file `make.j l, which is created by DocumenterTools.jl translates the markdown language to HTML-code.

Upload the code to your GitHub account, enable GitHub Pages for your project and your documentation will be displayed on your GitHub website <username>.github.io.