Adds docs and tests

.github/workflows/ci.yml

@@ -1,39 +1,73 @@
 name: CI
 on:
   push:
-    branches: [master]
+    branches:
+      - master
+    tags: ["*"]
   pull_request:
-    types: [opened, synchronize, reopened]
-# needed to allow julia-actions/cache to delete old caches that it has created
-permissions:
-  actions: write
-  contents: read
+  workflow_dispatch:
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 jobs:
   test:
-    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }}
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
+      actions: write
+      contents: read
     strategy:
       fail-fast: false
       matrix:
-        version: ['1.10', '1']
-        os: [ubuntu-latest, macOS-latest, windows-latest]
-        arch: [x64]
-        include:
-          # Also test against 32-bit Linux.
-          - version: '1'
-            os: ubuntu-latest
-            arch: x86
+        version:
+          - "1.10"
+          - "1.12"
+          - "pre"
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: julia-actions/cache@v1
+      - uses: julia-actions/cache@v2
+      - run: sudo apt-get update && sudo apt-get install -y xorg-dev mesa-utils xvfb libgl1 freeglut3-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev xsettingsd x11-xserver-utils
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         with:
-          file: lcov.info
+          files: lcov.info
           token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write # needed to allow julia-actions/cache to proactively delete old caches that it has created
+      contents: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: "1"
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+      - name: Run doctests
+        shell: julia --project=docs --color=yes {0}
+        run: |
+          using Documenter: DocMeta, doctest
+          using PiecewiseLinearOpt
+          DocMeta.setdocmeta!(PiecewiseLinearOpt, :DocTestSetup, :(using PiecewiseLinearOpt); recursive=true)
+          doctest(PiecewiseLinearOpt)

.gitignore

@@ -5,3 +5,5 @@ Manifest.toml
 *.DS_Store
 .DS_Store
 .vscode/settings.json
+coverage/
+docs/build/

Project.toml

@@ -12,10 +12,15 @@ Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 HiGHS = "1"
 JuMP = "1"
 julia = "1.10"
+LinearAlgebra = "1"
+Random = "1"
+Aqua = "0.8"
+Test = "1"
 
 [extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test", "HiGHS"]
+test = ["Aqua", "Test", "HiGHS"]

README.md

@@ -2,6 +2,7 @@
 
 [![Build Status](https://github.com/jump-dev/PiecewiseLinearOpt.jl/workflows/CI/badge.svg)](https://github.com/jump-dev/PiecewiseLinearOpt.jl/actions?query=workflow%3ACI)
 [![codecov](https://codecov.io/gh/jump-dev/PiecewiseLinearOpt.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/jump-dev/PiecewiseLinearOpt.jl)
+[![Aqua QA](https://juliatesting.github.io/Aqua.jl/dev/assets/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
 [PiecewiseLinearOpt.jl](https://github.com/jump-dev/PiecewiseLinearOpt.jl) is a
 JuMP extension for modeling optimization problems containing piecewise linear

docs/Project.toml

@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
+JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
+PiecewiseLinearOpt = "0f51c51e-adfa-5141-8a04-d40246b8977c"

docs/make.jl

@@ -0,0 +1,34 @@
+
+# julia --project=docs docs/make.jl 
+using PiecewiseLinearOpt
+using Documenter
+
+DocMeta.setdocmeta!(
+    PiecewiseLinearOpt,
+    :DocTestSetup,
+    :(using PiecewiseLinearOpt, JuMP);
+    recursive = true,
+)
+
+makedocs(;
+    modules = [PiecewiseLinearOpt],
+    sitename = "PiecewiseLinearOpt.jl",
+    authors = "Joey Huchette and contributors",
+    format = Documenter.HTML(;
+        canonical = "https://jump-dev.github.io/PiecewiseLinearOpt.jl",
+        edit_link = "master",
+        assets = String[],
+    ),
+    pages = [
+        "Home" => "index.md",
+        "Tutorial" => "tutorial.md",
+        "Formulation Methods" => "methods.md",
+        "API Reference" => "api.md",
+    ],
+    warnonly = true,
+)
+
+deploydocs(;
+    repo = "github.com/jump-dev/PiecewiseLinearOpt.jl",
+    devbranch = "master",
+)

docs/src/api.md

@@ -0,0 +1,58 @@
+# API Reference
+
+## Main function
+
+```@docs
+piecewiselinear
+```
+
+## PWL function types
+
+```@docs
+PWLFunction
+UnivariatePWLFunction
+BivariatePWLFunction
+```
+
+## Direction enum
+
+```@docs
+PiecewiseLinearOpt.DIRECTION
+```
+
+## Univariate methods
+
+```@docs
+Logarithmic
+LogarithmicEmbedding
+LogarithmicIndependentBranching
+Incremental
+NativeSOS2
+ZigZagBinary
+ZigZagInteger
+```
+
+## Bivariate methods
+
+```@docs
+K1
+SixStencil
+NineStencil
+UnionJack
+```
+
+## Multivariate methods
+
+```@docs
+ConvexCombination
+DisaggregatedLogarithmic
+MultipleChoice
+```
+
+## Internal types
+
+```@docs
+PiecewiseLinearOpt.SegmentPointRep
+PiecewiseLinearOpt.SegmentHyperplaneRep
+PiecewiseLinearOpt.AffineFunction
+```

docs/src/index.md

@@ -0,0 +1,67 @@
+```@meta
+CurrentModule = PiecewiseLinearOpt
+```
+
+# PiecewiseLinearOpt.jl
+
+[PiecewiseLinearOpt.jl](https://github.com/jump-dev/PiecewiseLinearOpt.jl) is a
+[JuMP](https://github.com/jump-dev/JuMP.jl) extension for modeling optimization
+problems containing piecewise linear functions. It provides MIP (mixed-integer
+programming) formulations for embedding piecewise linear functions into
+optimization models.
+
+This package is an accompaniment to the paper:
+
+> J. Huchette and J.P. Vielma, [_Nonconvex piecewise linear functions: Advanced
+> formulations and simple modeling tools_](https://arxiv.org/abs/1708.00050),
+> Operations Research, 2019.
+
+## Features
+
+- **Univariate piecewise linear functions**: Approximate any univariate function
+  with a piecewise linear function defined on a set of breakpoints.
+- **Bivariate piecewise linear functions**: Approximate bivariate functions on
+  triangulated grids with multiple triangulation patterns.
+- **Multiple MIP formulations**: Choose from a variety of formulations with
+  different trade-offs in terms of the number of binary variables, continuous
+  variables, and constraints.
+- **Graph, epigraph, and hypograph modes**: Model the graph of the function
+  exactly, or relax to epigraph/hypograph constraints.
+
+## Installation
+
+Install PiecewiseLinearOpt using the Julia package manager:
+
+```julia
+import Pkg
+Pkg.add("PiecewiseLinearOpt")
+```
+
+## Getting help
+
+If you need help, please ask a question on the
+[JuMP community forum](https://jump.dev/forum).
+
+If you have a reproducible example of a bug, please open a
+[GitHub issue](https://github.com/jump-dev/PiecewiseLinearOpt.jl/issues/new).
+
+## License
+
+`PiecewiseLinearOpt.jl` is licensed under the
+[MIT license](https://github.com/jump-dev/PiecewiseLinearOpt.jl/blob/master/LICENSE.md).
+
+## Quick start
+
+```julia
+using JuMP, PiecewiseLinearOpt, HiGHS
+
+model = Model(HiGHS.Optimizer)
+set_silent(model)
+@variable(model, x)
+# Approximate sin(x) on [0, 2π] with breakpoints every 0.5
+z = piecewiselinear(model, x, 0:0.5:2pi, sin)
+@objective(model, Max, z)
+optimize!(model)
+value(x)  # ≈ π/2
+value(z)  # ≈ 1.0
+```