Merge pull request #3229 from ERGO-Code/od/update-docs

[docs] update to Documenter@1 and Clang@0.19

Author: galabovaa

.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

docs/.gitignore

@@ -1,2 +1,2 @@
 Manifest.toml
-c_api_gen/libhighs.jl
+libhighs.jl

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"

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

docs/c_api_gen/HConfig.h

@@ -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,16 +49,15 @@ 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,
     linkcheck_ignore = [
         "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",

docs/c_api_gen/build.jl

@@ -1,5 +1,9 @@
 # [C](@id c-api)
 
+```@docs
+HighsInt
+```
+
 ```@autodocs
 Modules = [Main]
 Filter = t -> startswith("$t", "Highs")