Refactoring

JuliaQUBO · Apr 11, 2023 · 0de212c · 0de212c
1 parent aee79c3
commit 0de212c
Show file tree

Hide file tree

Showing 6 changed files with 137 additions and 112 deletions.
diff --git a/.github/workflows/documentation.yml → .github/workflows/docs.yml b/.github/workflows/documentation.yml → .github/workflows/docs.yml
@@ -19,4 +19,4 @@ jobs:
       - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
-        run: julia --project=docs/ docs/make_qubo.jl
+        run: julia --project=docs/ docs/make.jl
diff --git a/.github/workflows/multi_documentation.yml → .github/workflows/multidocs.yml b/.github/workflows/multi_documentation.yml → .github/workflows/multidocs.yml
@@ -17,4 +17,4 @@ jobs:
       - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
-        run: julia --project=docs/ docs/make.jl
+        run: julia --project=docs/ docs/multimake.jl
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,79 +1,26 @@
 using Documenter
-using MultiDocumenter
 
-temp_dir = mktempdir()
-
-
-docs = [
-    MultiDocumenter.MultiDocRef(
-        upstream = joinpath(temp_dir, "QUBO.jl"),
-        path = "QUBO.jl",
-        name = "QUBO.jl",
-        giturl = "https://github.com/psrenergy/QUBO.jl.git",
-        branch ="gh-pages"
-    ),
-    MultiDocumenter.MultiDocRef(
-        upstream = joinpath(temp_dir, "ToQUBO.jl"),
-        path = "ToQUBO.jl",
-        name = "ToQUBO.jl",
-        giturl = "https://github.com/psrenergy/ToQUBO.jl.git",
-    ),
-    MultiDocumenter.MultiDocRef(
-        upstream = joinpath(temp_dir, "QUBODrivers.jl"),
-        path = "QUBODrivers.jl",
-        name = "QUBODrivers.jl",
-        giturl = "https://github.com/psrenergy/QUBODrivers.jl.git",
-    ),
-    MultiDocumenter.MultiDocRef(
-        upstream = joinpath(temp_dir, "QUBOTools.jl"),
-        path = "QUBOTools.jl",
-        name = "QUBOTools.jl",
-        giturl = "https://github.com/psrenergy/QUBOTools.jl.git",
+makedocs(;
+    doctest=true,
+    clean=true,
+    format=Documenter.HTML(
+        assets=[
+            "assets/extra_styles.css",
+            # "assets/favicon.ico",
+        ],
+        mathengine=Documenter.KaTeX(),
+        sidebar_sitename=false,
     ),
-
-]
-
-outpath = mktempdir()
-
-
-MultiDocumenter.make(
-    outpath,
-    docs;
-    search_engine = MultiDocumenter.SearchConfig(
-        index_versions = ["stable"],
-        engine = MultiDocumenter.FlexSearch
-    ),
-    rootpath = "/QUBO.jl",
+    sitename="QUBO.jl",
+    authors="Pedro Xavier and Pedro Ripper and Tiago Andrade and Joaquim Garcia and David Bernal",
+    pages=[
+        "Home" => "index.md"
+    ],
+    workdir="."
 )
 
-gitroot = normpath(joinpath(@__DIR__, ".."))
-run(`git pull`)
-outbranch = "gh-multi-pages"
-has_outbranch = true
-if !success(`git checkout $outbranch`)
-    has_outbranch = false
-    if !success(`git checkout -b $outbranch`)
-        @error "Cannot create new orphaned branch $outbranch."
-        exit(1)
-    end
-end
-
-for file in readdir(gitroot; join = true)
-    endswith(file, ".git") && continue
-    rm(file; force = true, recursive = true)
-end
-for file in readdir(outpath)
-    cp(joinpath(outpath, file), joinpath(gitroot, file))
-end
-run(`git add .`)
-if success(`git commit -m 'Aggregate documentation'`)
-    @info "Pushing updated documentation."
-    if has_outbranch
-        run(`git push`)
-    else
-        run(`git push -u origin $outbranch`)
-    end
-    run(`git checkout master`)
+if "--skip-deploy" ∈ ARGS
+    @warn "Skipping deployment"
 else
-    @info "No changes to aggregated documentation."
+    deploydocs(raw"github.com/psrenergy/QUBO.jl.git", push_preview=true)
 end
diff --git a/docs/make_qubo.jl b/docs/make_qubo.jl
diff --git a/docs/multimake.jl b/docs/multimake.jl
@@ -0,0 +1,103 @@
+using Documenter
+using MultiDocumenter
+
+temp_dir = mktempdir()
+
+docs = [
+    MultiDocumenter.MultiDocRef(
+        upstream=joinpath(temp_dir, "QUBO.jl"),
+        path="QUBO.jl",
+        name="QUBO.jl",
+        giturl="https://github.com/psrenergy/QUBO.jl.git",
+        branch="gh-pages",
+    ),
+    MultiDocumenter.MultiDocRef(
+        upstream=joinpath(temp_dir, "ToQUBO.jl"),
+        path="ToQUBO.jl",
+        name="ToQUBO.jl",
+        giturl="https://github.com/psrenergy/ToQUBO.jl.git",
+        branch="gh-pages",
+    ),
+    MultiDocumenter.MultiDocRef(
+        upstream=joinpath(temp_dir, "QUBODrivers.jl"),
+        path="QUBODrivers.jl",
+        name="QUBODrivers.jl",
+        giturl="https://github.com/psrenergy/QUBODrivers.jl.git",
+        branch="gh-pages",
+    ),
+    MultiDocumenter.MultiDocRef(
+        upstream=joinpath(temp_dir, "QUBOTools.jl"),
+        path="QUBOTools.jl",
+        name="QUBOTools.jl",
+        giturl="https://github.com/psrenergy/QUBOTools.jl.git",
+        branch="gh-pages",
+    ),
+]
+
+function buildmultidocs(path::AbstractString, docs)
+    MultiDocumenter.make(
+        path,
+        docs;
+        search_engine=MultiDocumenter.SearchConfig(
+            index_versions=["stable"],
+            engine=MultiDocumenter.FlexSearch
+        ),
+        rootpath="/QUBO.jl"
+    )
+
+    return nothing
+end
+
+function deploymultidocs(path::AbstractString; branch::String="gh-multi-pages", main::String="main")
+    root_path = normpath(joinpath(@__DIR__, ".."))
+
+    run(`git pull`)
+
+    has_branch = true
+
+    if !success(`git checkout $branch`)
+        has_branch = false
+        if !success(`git checkout -b $branch`)
+            @error "Cannot create new orphaned branch $branch"
+            exit(1)
+        end
+    end
+
+    for file in readdir(root_path; join=true)
+        endswith(file, ".git") && continue
+        rm(file; force=true, recursive=true)
+    end
+
+    for file in readdir(path)
+        cp(joinpath(path, file), joinpath(root_path, file))
+    end
+
+    run(`git add .`)
+
+    if success(`git commit -m 'Aggregate documentation'`)
+        @info "Pushing updated documentation"
+
+        if has_branch
+            run(`git push`)
+        else
+            run(`git push -u origin $branch`)
+        end
+
+        run(`git checkout $main`)
+    else
+        @info "No changes to aggregated documentation"
+    end
+
+    return nothing
+end
+
+# creates if not exists
+build_path = mkpath(joinpath(@__DIR__, "build_path"))
+
+buildmultidocs(build_path, docs)
+
+if "--skip-deploy" ∈ ARGS
+    @warn "Skipping deployment"
+else
+    deploymultidocs(build_path; main="master")
+end
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -5,23 +5,24 @@
 
 `QUBO.jl` is an all-in-one package for working with QUBO formulations in [JuMP](https://github.com/jump-dev/JuMP.jl) and interfacing with QUBO solvers. This project aggregates three complementary packages: [`ToQUBO.jl`](https://github.com/psrenergy/ToQUBO.jl), [`QUBODrivers.jl`](https://github.com/psrenergy/QUBODrivers.jl) and [`QUBOTools.jl`](https://github.com/psrenergy/QUBOTools.jl).
 
-## What is a QUBO?
+## QUBO?
 
 QUBO is an acronym for *Quadratic Unconstrained Binary Optimization*. So every QUBO problem is comprised of:
-- an objective function at most quadratic
+- a linear or quadratic objective function
 - no constraints
 - binary variables
 
-We can represent a QUBO problem as follows.
+We can represent such problem as follows:
 
 ```math
 \begin{array}{rl}
    \min          & \mathbf{x}' Q\,\mathbf{x} \\
-   \mathrm{s.t.} & \mathbf{x} \in \mathbb{B}^{n}
+   \textrm{s.t.} & \mathbf{x} \in \mathbb{B}^{n}
 \end{array}
 ```
 
-QUBOs are suited for representing non-convex global optimization problems. With that said, the significant advances in computing systems and algorithms specialized for sampling QUBOs have contributed to their popularity.
+QUBOs are suited for representing non-convex global optimization problems.
+With that said, the significant advances in computing systems and algorithms specialized for sampling QUBOs have contributed to their popularity.
 
 Some of the paradigms that stand out for running QUBOs are quantum gate-based optimization algorithms (QAOA and VQE), quantum annealers and hardware-accelerated platforms (Coherent Ising Machines and Simulated Bifurcation Machines).
 
@@ -46,10 +47,8 @@ julia> ]add https://github.com/psrenergy/QUBO.jl#master
 ### Example
 
 ```julia
-using QUBO
 using JuMP
-ToQUBO = QUBO.ToQUBO
-Anneal = QUBO.QUBODrivers
+using QUBO
 
 model = Model(() -> ToQUBO.Optimizer(ExactSampler.Optimizer))
 
@@ -60,14 +59,15 @@ model = Model(() -> ToQUBO.Optimizer(ExactSampler.Optimizer))
 optimize!(model)
 
 for i = 1:result_count(model)
-    xᵢ = value.(x, result = i)
-    yᵢ = objective_value(model, result = i)
-    println("f($xᵢ) = $yᵢ")
+    xi = value.(x, result = i)
+    yi = objective_value(model, result = i)
+
+    println("f($xi) = $yi")
 end
 
 ```
 
-
+```@raw html
 <div align="center">
     <h2>QUBO.jl Packages</h2>
     <a href="https://github.com/psrenergy/ToQUBO.jl">
@@ -80,3 +80,4 @@ end
         <img width="200px" src="https://raw.githubusercontent.com/psrenergy/QUBOTools.jl/main/docs/src/assets/logo.svg" alt="QUBOTools.jl" />
     </a>
 </div>
+```