305 solve documentation

[jbcaillau]

closes #305

[jbcaillau]

second thoughts: for the problem definition, i really prefer to keep the reference to the grammar written as an expression.

• i don't think it's misleading as concrete examples are immediately provided
• i am OK to change my mind if users complain
• i like the fact that Julia is flexible enough to allow a description in Julia of a DSL that extends its syntax

[jbcaillau]

@ocots @PierreMartinon @gergaud it is important to promote the ability to solve on GPU, so i've added a section "Solve on GPU". it is better if the three of you look at it, not me. i'll take care of the update of "Problem definition" section, adding remarks on the limitations due to ExaModels for GPU solving.

[jbcaillau]

@ocots can you please recall how to generate the doc on a branch (not main)? i find it more convenient not to build locally and rely on CI in draft mode.

[github-actions]

Breakage test results
Date: 2025-07-05 21:40:08

Name	Latest	Stable
OptimalControlProblems.jl
Tutorials.jl

[ocots]

second thoughts: for the problem definition, i really prefer to keep the reference to the grammar written as an expression.

• i don't think it's misleading as concrete examples are immediately provided
• i am OK to change my mind if users complain
• i like the fact that Julia is flexible enough to allow a description in Julia of a DSL that extends its syntax

I think that having all the expressions at first, then the examples could be nice. Always the same, when you learn, you want details, when you already know, you want to go straight to the point. If you have all the syntax in one block, then, maybe you can retrieve something you forgot.

That's why I put the docstrings first here.

[ocots]

@ocots can you please recall how to generate the doc on a branch (not main)? i find it more convenient not to build locally and rely on CI in draft mode.

https://documenter.juliadocs.org/stable/lib/public/#Documenter.deploydocs

Replace

push_preview = false,

by

push_preview = true,

push_preview a boolean that specifies if preview documentation should be deployed from pull requests or not. If your published documentation is hosted at "https://USER.github.io/PACKAGE.jl/stable, by default the preview will be hosted at "https://USER.github.io/PACKAGE.jl/previews/PR##". This feature works for pull requests with head branch in the same repository, i.e. not from forks.

To access to the doc:

"https://USER.github.io/PACKAGE.jl/previews/PR##"

where you replace PR## by PR580.