By: DSB
Re-posted from: https://medium.com/coffee-in-a-klein-bottle/creating-and-deploying-your-julia-package-documentation-1d09ddc90474?source=rss-8bd6ec95ab58------2
A tutorial on how to create and deploy your Julia Package documentation using Documenter.jl and GitHub Actions.
If you are developing a new package for Julia, you might’ve followed the steps in this article, and is now wondering how to create the documentation for your package. Well, this is what this article is for. Here, our new package is also called VegaGraphs.jl, which is a package that I’m developing at the moment.
In this tutorial I’ll be using the package Documenter.jl together with the GitHub Actions plugin. The Documenter.jl package will help us create the documentation, and the GitHub Actions plugin will create a bot for us that will publish our documentation on our GitHub page.
1. Creating Docstring
First of all, when you write the functions in your package, above each function you should write a Docstring explaining the arguments used in the function, what the function does, etc.
# Example of function inside ./src/VegaGraphs.jl
"""
MyFunction(x,y)
This is an example of Docstring. This function receives two
numbers x and y and returns the sum of the squares.
```math
x^2 + y^2
```
"""
function MyFunction(x,y)
return x^2+y^2
end
Note that you should use triple quotes, and place the text right above the function you are documenting. Also, you may use LaTeX to write math equations, as shown in the lines:
```math
x^2 + y^2
```
When you generate your documentation, this equation will be properly rendered, and you will have a beautiful mathematical equation.
2. Setting up Documenter.jl
Next we must set up the Documenter.jl. To do this, first create a folder named docs and inside of it create a file named make.jland another folder named ./src . Your package folder should look something like this:
VegaGraphs/
├── docs/
│ └── make.jl
│ └── src/
├── src/
│ └── VegaGraphs.jl
...
Inside the make.jl file we will write the code that Documenter.jl will use to create a nice webpage for our documentation. Inside make.jl write the following (changing the name of the package from VegaGraph to yours):
# Inside make.jl
push!(LOAD_PATH,"../src/")
using VegaGraphs
using Documenter
makedocs(
sitename = "VegaGraphs.jl",
modules = [VegaGraphs],
pages=[
"Home" => "index.md"
])
deploydocs(;
repo="github.com/USERNAME/VegaGraphs.jl",
)
Most of the code here is self-explanatory. You are defining the name the website for the documentation, the module which you will be documenting, and the pages your website will have. For now, our documentation will only have “Home”, and the information that will be on this page will be inside the index.m file.
Inside the ./docs/src you need to create the file named index.md. This is a markdown file where you will write how the “Home” page should look like. Here is an example:
# VegaGraphs.jl
*The best summation package.*
## Package Features
- Sum the squares of two numbers
## Function Documentation
```@docs
MyFunction
```
Everything here should be familiar to you if you know markdown. The only thing that looks different are the last 4 lines. Here is where our Docstring comes in. The Documenter.jl package will take the Docstring from the function MyFunction and place where we wrote:
```@docs
MyFunction
```
As your create new functions, just add more of this to your index.md , and you will rapidly create your package’s documentation.
The final step in regards to Documenter.jl is to build the whole thing:
# from your terminal,inside the ./docs/src
# Remember to install Documenter.jl before running this
julia make.jl
After running this command, a new folder called build will be created inside the docs , and this folder will contain all the html files for your documentation. You may now open this folder
3. Deploying your Documentation with GitHub Actions
Your website containing the documentation for the package is already created, and you may host the webpages using any method you want. In this section, I’ll then explain how to use GitHub Actions to automatically publish the documentation using GitHub pages.
Assuming you followed this article here on how to develop your package, you already have GitHub Actions working on the background. What you must do now is create a file named Documentation.yml inside the .github/workflows folder. Inside this file, you should have something like this:
name: Documentation
on:
push:
branches:
- master
tags: '*'
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: julia-actions/setup-julia@latest
with:
version: '1.5'
- name: Install dependencies
run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
- name: Build and deploy
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
run: julia --project=docs/ docs/make.jl
You can pretty much copy and past the code above, and the next time you push new commits to your repository, the bot will run and generate the documentation. Also, note that it will create a branch named “gh-pages”. This is the branch containing the webpages for the documentation.
To use GitHub pages for hosting our documentation, we must enable GitHub pages on the repository containing the package. To do this, just go to the repository GitHub’s page, click on setttings , scroll down to the “GitHub Pages” section and enable it.
After doing all this, your documentation will be available at “https://username.github.io/VegaGraphs.jl/dev.
And you now has a beautiful website for your documentation.
Creating and Deploying your Julia Package Documentation was originally published in Coffee in a Klein Bottle on Medium, where people are continuing the conversation by highlighting and responding to this story.