Tutorial about expressions

[dourouc05]

I wished I had this when I started with CP stuff, so here it is :). It's mostly agnostic to #1474, only two sentences would need to be changed.

What is the preferred way of exploring the terms of a function? For now, I've been mostly using the terms member; should it be advertised more as a recommended practice?

[odow]

This is great! One major comment: should we consider formatting this as a literate tutorial so we make sure it runs? The alternative is to have everything as doctests.

Currently people can't copy-paste the code and have it run.

[dourouc05]

I have no idea how to make a literate tutorial or doctests, that's the main reason why I started in this way. I saw inhttps://github.com/jump-dev/MathOptInterface.jl/blob/master/docs/src/tutorials/example.md that there are a lot of jldoctest: I guess this is related to https://juliadocs.github.io/Documenter.jl/stable/man/doctests/#REPL-Examples?

[odow]

that there are a lot of jldoctest

Yeah. These blocks get run on build to check that they reproduce the output. That way you can make sure you don't have typos in the documentation.

The alternative is Literate.jl (https://github.com/fredrikekre/Literate.jl)

Here's one from JuMP:

https://github.com/jump-dev/JuMP.jl/blob/master/docs/src/tutorials/Getting%20started/an_introduction_to_julia.jl

Here's the modification to make to the docs/make.jl

https://github.com/jump-dev/JuMP.jl/blob/5a739673e27997cb783ef3a7f827de974a18d858/docs/make.jl#L39-L66

[dourouc05]

I've converted the tutorial into doctests. I checked them in the REPL while working on it, I hope the tests will pass…

[dourouc05]

@odow Could you please have a look at the current failures? It really looks like different versions of Julia have different outputs regarding types.

[odow]

Yeah the docs run in Julia 1.0, which has different printing.

A secret is to run this in Julia 1.0 and it will fix everything:

MathOptInterface.jl/docs/make.jl

Lines 3 to 6 in 6f166a9

	"""
	Pass `julia docs/make.jl --fix` to rebuild the doctests.
	"""
	const _FIX = findfirst(isequal("--fix"), ARGS) !== nothing

[dourouc05]

It now seems to pass :D!

[odow]

Looks good. A couple of points.

[odow]

I'm surprised this worked. I thought it had to be [`Utilities.scalarize`](@ref)

[odow]

LGTM. Much better than before!