diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 28690e0105c..f73c233618d 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -9,11 +9,16 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: julia-actions/setup-julia@latest with: - version: '1.9' + version: '1.12' + - name: Install dependencies + shell: julia --color=yes --project=docs/ {0} + run: | + using Pkg + Pkg.instantiate() - name: Build and deploy + run: julia --project=docs/ --color=yes docs/make.jl env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: julia --project=docs/ docs/make.jl diff --git a/docs/.gitignore b/docs/.gitignore index 15730ee950d..a2fe56f05cf 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,2 @@ Manifest.toml -c_api_gen/libhighs.jl +libhighs.jl diff --git a/docs/Project.toml b/docs/Project.toml index 1f27461d656..0e6fb77d07e 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -3,5 +3,6 @@ Clang = "40e3b903-d033-50b4-a0cc-940c62c95e31" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" [compat] -#Clang = "0.14, 0.17, 0.18" -Documenter = "0.27" +Clang = "0.19" +Documenter = "1" +julia = "1.12" diff --git a/docs/README.md b/docs/README.md index 86464838fda..8c28bba2512 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,10 +9,12 @@ To edit the documentation, checkout a branch and edit the Markdown files in the ## Building the documentation -To build locally, [install Julia](https://julialang.org/downloads/), then (from the `docs` directory) run: +To build locally, [install Julia](https://julialang.org/downloads/), then, from +the repository root, run: ``` bash -$ julia make.jl +$ julia --project=docs -e 'using Pkg; Pkg.instantiate()' +$ julia --project=docs docs/make.jl ``` The first time you run this command, Julia will download and install the diff --git a/docs/c_api_gen/HConfig.h b/docs/c_api_gen/HConfig.h deleted file mode 100644 index 0f1329b918b..00000000000 --- a/docs/c_api_gen/HConfig.h +++ /dev/null @@ -1 +0,0 @@ -// A dummy file to fix a warning when Julia parses the C API. diff --git a/docs/c_api_gen/build.jl b/docs/c_api_gen/build.jl deleted file mode 100644 index 3417d09bfa1..00000000000 --- a/docs/c_api_gen/build.jl +++ /dev/null @@ -1,48 +0,0 @@ -#=* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -* * -* This file is part of the HiGHS linear optimization suite * -* * -* Written and engineered 2008-2023 by Julian Hall, Ivet Galabova, * -* Leona Gottwald and Michael Feldmeier * -* Available as open-source under the MIT License * -* * -* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *=# - -import Clang: Generators - -highs_src = joinpath(dirname(dirname(@__DIR__)), "highs") -c_api = joinpath(highs_src, "interfaces", "highs_c_api.h") -libhighs_filename = joinpath(@__DIR__, "libhighs.jl") - -Generators.build!( - Generators.create_context( - [c_api, joinpath(highs_src, "util", "HighsType.h")], - [Generators.get_default_args(); "-I$highs_src"; "-I$(@__DIR__)"], - Dict{String,Any}( - "general" => Dict{String,Any}( - "output_file_path" => libhighs_filename, - "library_name" => "libhighs", - "print_using_CEnum" => false, - "extract_c_comment_style" => "doxygen", - ) - ), - ), -) - -write( - libhighs_filename, - replace( - read(libhighs_filename, String), - "[`HighsInt`](@ref)" => "`HighsInt`", - ), -) - -open(libhighs_filename, "a") do io - for line in readlines(c_api) - m = match(r"const HighsInt kHighs([a-zA-Z]+) = (-?[0-9]+);", line) - if m === nothing - continue - end - println(io, "const kHighs$(m[1]) = HighsInt($(m[2]))") - end -end diff --git a/docs/make.jl b/docs/make.jl index f0352a14a31..75d6a33d8a2 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,19 +6,35 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *=# -import Pkg -Pkg.activate(@__DIR__) -Pkg.instantiate() - import Documenter # ============================================================================== # Parse and build docstrings from the C API # ============================================================================== -const libhighs = "" -include(joinpath(@__DIR__, "c_api_gen", "build.jl")) -include(joinpath(@__DIR__, "c_api_gen", "libhighs.jl")) +import Clang + +let + highs = joinpath(dirname(@__DIR__), "highs") + c_api = joinpath(highs, "interfaces", "highs_c_api.h") + ctx = Clang.Generators.create_context( + [c_api, joinpath(highs, "util", "HighsInt.h")], + vcat(Clang.Generators.get_default_args(), "-I$highs"), + Dict( + "general" => Dict( + "library_name" => "libhighs", + "output_file_path" => joinpath(@__DIR__, "libhighs.jl"), + "print_using_CEnum" => false, + "extract_c_comment_style" => "doxygen", + ), + ), + ) + Clang.Generators.build!(ctx) + include(joinpath(@__DIR__, "libhighs.jl")) +end + +# Add a docstring for HighsInt +@doc " HighsInt\n\nThe constant `Cint`." HighsInt # ============================================================================== # Make the documentation @@ -33,7 +49,6 @@ Documenter.makedocs( prettyurls = get(ENV, "CI", nothing) == "true", highlights = ["yaml"], ), - strict = !("strict=false" in ARGS), doctest = ("doctest=only" in ARGS) ? :only : true, repo = "https://github.com/ERGO-Code/HiGHS/tree/latest{path}", linkcheck = false, @@ -41,8 +56,8 @@ Documenter.makedocs( "https://crates.io/crates/highs", "https://crates.io/crates/good_lp", "https://link.springer.com/article/10.1007/s12532-017-0130-5", - "https://link.springer.com/article/10.1007/s12532-020-00181-8", - "https://github.com/ERGO-Code/HiGHS/blob/master/highs/Highs.h" + "https://link.springer.com/article/10.1007/s12532-020-00181-8", + "https://github.com/ERGO-Code/HiGHS/blob/master/highs/Highs.h" ], pages = [ "About" => "index.md", diff --git a/docs/src/interfaces/c_api.md b/docs/src/interfaces/c_api.md index 744c68a052f..9d3d7e8dfa7 100644 --- a/docs/src/interfaces/c_api.md +++ b/docs/src/interfaces/c_api.md @@ -1,5 +1,9 @@ # [C](@id c-api) +```@docs +HighsInt +``` + ```@autodocs Modules = [Main] Filter = t -> startswith("$t", "Highs")