Constraint Solver Part 12: Documentation and small changes

Series: Constraint Solver in Julia

This is part 12 of the series about: How to build a Constraint Programming solver?

It’s a bit different this time. This is a series and sometimes I make just small changes that I normally wouldn’t blog about.
In this series I want to post updates as frequently as possible to keep you updated.

In this post you can learn how to write a documentation to your Julia package. You can visit mine here: ConstraintSolver.jl documentation.

Additionally a contributor made a small change to speed up the graph coloring example. I will add an update on benchmarks on sudoku, killer sudoku with only a handful of test cases as it’s time consuming to create them by hand as well as benchmarks on Graph Coloring in comparison to Google OR-Tools and some more MIP solvers (Cbc.jl and Gurobi.jl).

Then we know how fast this solver is and can either focus on performance in some cases or keep building forward by creating other constraints and objectives as the amount is still quite limited.

Creating a documentation

I use Documenter.jl for creating a documentation.

There are only some things that I think are important for you which I didn’t see directly in the documentation.

For creating a documentation using Travis you can completely rely on on the documentation of Documenter.jl.

In general it creates a docs folder in your repository and you can write a normal markdown documentation but also be able to use the code documentation of functions from your code i.e

## User interface functions

``@docs
ConstraintSolver.init
add_var!
``

<- should be ““`” (3 of them) but my markdown can’t handle it :/

will create:

Docs

and will be updated whenever you change the function documentation in your code i.e

"""
    init()

Initialize the constraint model object
"""
function init()

Now to publish this directly on GitHub pages one needs to set
Repo-> Settings – GitHub Pages to gh-pages (might get activated later as you currently don’t have this branch.)

The html code needs to be created from your markdown files and either Travis can do this or for this case GitHub Actions.

For this you can create a new .yml file in the .github/workflows folder. A new file there represents a new GitHub Actions workflow.
I call mine docs.yml and it contains:

name: Documentation

on: [push, pull_request]

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        julia-version: [1.2.0]
        julia-arch: [x86]
        os: [ubuntu-latest]
    steps:
      - uses: actions/checkout@v1.0.0
      - uses: julia-actions/setup-julia@latest
        with:
          version: ${{ matrix.julia-version }}
      - name: Install dependencies
        run: julia --project=docs/ -e 'using Pkg; Pkg.instantiate()'
      - name: Build and deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: julia --project=docs/ docs/make.jl

The documentation…