Merge pull request #64 from psrenergy/px/docs

Write Docs for `v0.1.5`

.github/workflows/documentation.yml

@@ -14,10 +14,12 @@ jobs:
       - uses: julia-actions/setup-julia@latest
         with:
           version: '1.6'
+      - name: Develop ToQUBO.jl
+        run: julia --project=docs -e 'using Pkg; Pkg.develop(path=pwd())'
       - uses: julia-actions/julia-buildpkg@latest
         with: 
-            project: "docs/"
+            project: "docs"
       - 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/make.jl

CITATION.bib

@@ -1,7 +1,7 @@
 % If you use this software, please cite it as below.
 @software{toqubo:2023,
   author       = {Pedro Maciel Xavier and Pedro Ripper and Tiago Andrade and Joaquim Dias Garcia and David E. Bernal Neira},
-  title        = {ToQUBO.jl},
+  title        = {{ToQUBO.jl}},
   month        = {feb},
   year         = {2023},
   publisher    = {Zenodo},

README.md

@@ -28,10 +28,7 @@ ToQUBO.jl was written as a [MathOptInterface](https://github.com/jump-dev/MathOp
 
 ### Installation
 ToQUBO is available via Julia's Pkg:
-```julia
-julia> ]add ToQUBO
-```
-or
+
 ```julia
 julia> using Pkg
 
@@ -53,9 +50,10 @@ 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
 ```
 
@@ -135,15 +133,15 @@ If you think this list is incomplete, consider creating an [Issue](https://githu
 ## Citing ToQUBO.jl
 If you use `ToQUBO.jl` in your work, we kindly ask you to include the following citation:
 ```tex
-@software{toqubo:2022,
-  author       = {Pedro Xavier and Tiago Andrade and Joaquim Garcia and David Bernal},
+@software{toqubo:2023,
+  author       = {Pedro Maciel Xavier and Pedro Ripper and Tiago Andrade and Joaquim Dias Garcia and David E. Bernal Neira},
   title        = {{ToQUBO.jl}},
-  month        = {mar},
-  year         = {2022},
+  month        = {feb},
+  year         = {2023},
   publisher    = {Zenodo},
-  version      = {v0.1.0},
-  doi          = {10.5281/zenodo.6387592},
-  url          = {https://doi.org/10.5281/zenodo.6387592}
+  version      = {v0.1.5},
+  doi          = {10.5281/zenodo.7644291},
+  url          = {https://doi.org/10.5281/zenodo.7644291}
 }
 ```
 

docs/Project.toml

@@ -4,14 +4,16 @@ DWaveNeal = "870cdf72-5502-4b10-839c-127ceab78f22"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
-MQLib = "16f11440-1623-44c9-850c-358a6c72f3c9"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
-QUBODrivers = "a3f166f7-2cd3-47b6-9e1e-6fbfe0449eb0"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+PythonPlot = "274fc56d-3b97-40fa-a1cd-1b4a50311bf9"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 ToQUBO = "9a412ddf-83fa-43b6-9748-7843c851aa65"
 
 [compat]
 CSV = "0.10"
+DWaveNeal = "0.4"
 DataFrames = "1.3"
 Documenter = "0.27"
 JuMP = "1"

docs/make.jl

@@ -7,24 +7,50 @@ DocMeta.setdocmeta!(
 )
 
 makedocs(;
-    modules=[ToQUBO],
-    doctest=true,
-    clean=true,
-    format=Documenter.HTML(
-        assets = ["assets/extra_styles.css", "assets/favicon.ico"],
-        mathengine=Documenter.MathJax2(),
-        sidebar_sitename=false,
+    modules = [ToQUBO],
+    doctest = true,
+    clean   = true,
+    format  = Documenter.HTML(
+        sidebar_sitename = false,
+        mathengine       = Documenter.KaTeX(
+            Dict(
+                :macros => Dict(
+                    raw"\set" => raw"\left\lbrace{#1}\right\rbrace"
+                )
+            )
+        ),
+        assets           = [
+            "assets/extra_styles.css",
+            "assets/favicon.ico",
+            asset("https://tikzjax.com/v1/fonts.css"; class = :css),
+            asset("https://tikzjax.com/v1/tikzjax.js"; class = :js),
+        ],
     ), 
-    sitename="ToQUBO.jl",
-    authors="Pedro Xavier and Tiago Andrade and Joaquim Garcia and David Bernal",
-    pages=[
+    sitename = "ToQUBO.jl",
+    authors  = "Pedro Maciel Xavier and Pedro Ripper and Tiago Andrade and Joaquim Dias Garcia and David E. Bernal Neira",
+    pages    = [
         "Home" => "index.md",
-        "Manual" => "manual.md",
+        "Manual" => [
+            "Getting Started"   => "manual/1-start.md",
+            "Running a Model"   => "manual/2-model.md",
+            "Gathering Results" => "manual/3-results.md",
+            "Compiler Settings" => "manual/4-settings.md",
+        ],
         "Examples" => [
-            "Knapsack" =>"examples/knapsack.md",
-            "Prime Factorization" => "examples/prime_factorization.md",
+            "Knapsack"               => "examples/knapsack.md",
+            "Prime Factorization"    => "examples/prime_factorization.md",
+            "Portfolio Optimization" => "examples/portfolio_optimization.md",
+        ],
+        "Booklet" => [
+            "Introduction"    => "booklet/1-intro.md",
+            "QUBO"            => "booklet/2-qubo.md",
+            "PBO"             => "booklet/3-pbo.md",
+            "Encoding"        => "booklet/4-encoding.md",
+            "Virtual Mapping" => "booklet/5-virtual.md",
+            "The Compiler"    => "booklet/6-compiler.md",
+            "Solvers"         => "booklet/7-solvers.md",
+            "Appendix"        => "booklet/8-appendix.md",
         ],
-        "Booklet" => "booklet.md"
     ],
     workdir="."
 )

docs/src/assets/extra_styles.css

@@ -1,4 +1,15 @@
 .docs-sidebar .docs-logo > img {
     max-height: 16rem !important;
     margin: auto;
-}
+}
+
+/* Center images & diagrams */
+p:has(img) {
+    text-align: center;
+    margin: 0 auto;
+}
+
+div.mermaid {
+    text-align: center;
+    margin: 0 auto;
+}

docs/src/assets/init.js

@@ -0,0 +1,24 @@
+/* Ref:
+** https://discourse.julialang.org/t/use-javascript-library-with-documenter-jl/34984/8
+*/
+require.config({
+    paths: {
+        mermaid: "https://cdnjs.cloudflare.com/ajax/libs/mermaid/9.4.0/mermaid.min"
+    }
+});
+
+require(['mermaid'], function (mermaid) {
+    mermaid.initialize({
+        startOnLoad : true,
+        theme       : 'neutral',
+        // themeVariables: {
+        //     primaryColor: '#BB2528',
+        //     primaryTextColor: '#fff',
+        //     primaryBorderColor: '#7C0000',
+        //     lineColor: '#F8B229',
+        //     secondaryColor: '#006100',
+        //     tertiaryColor: '#aaa',
+        //     noteBorderColor: '#ff0',
+        // }
+    })
+});

docs/src/booklet/1-intro.md

@@ -0,0 +1,11 @@
+# ToQUBO.jl Booklet
+
+This booklet aims to gather the theoretical and practical details behind `ToQUBO` and provide documentation for project internals.
+The target audience includes, among others, advanced users and those willing to contribute to the project.
+The latter are advised to read the following sections, as they give a glimpse of the ideas employed up to now.
+
+## Table of Contents
+```@contents
+Pages = ["2-qubo.md", "3-pbo.md", "4-encoding.md", "5-virtual.md", "6-compiler.md", "7-solvers.md", "8-appendix.md"]
+Depth = 2
+```