Enhance docs (#46)

* Add logo

* docs: add the UAI file format descriptions

* docs: improve home page

* Improve UAI file descriptions and fix unresolved path

* docs: enhance probabilities with latex equations

* docs: add link to local descriptions of UAI file formats

* Add a background section

* Improve letters that denote different sets of vars

* Improve grammar

* docs: improve API section

* Keep the Index order consistent with the order of appearance

* Fix scaling of TikzPictures

* docs: show network above the var descriptions

* Move docs CI build to a separate file

* docs: use setup-julia@latest

* docs: update apt-get packages on CI

* docs: delete old docs CI config

* docs: update development GitHub branch

Author: mroavi

.github/workflows/CI.yml

@@ -37,23 +37,3 @@ jobs:
       - uses: codecov/codecov-action@v3
         with:
           files: lcov.info
-  docs:
-    name: Documentation
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
-        with:
-          version: '1'
-      - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-docdeploy@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - run: |
-          julia --project=docs -e '
-            using Documenter: DocMeta, doctest
-            using TensorInference
-            DocMeta.setdocmeta!(TensorInference, :DocTestSetup, :(using TensorInference); recursive=true)
-            doctest(TensorInference)'

.github/workflows/documentation.yml

@@ -0,0 +1,30 @@
+# Based on: https://documenter.juliadocs.org/stable/man/hosting/#GitHub-Actions
+
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      # TexLive installation (taken from https://github.com/JuliaTeX/TikzPictures.jl/blob/master/.github/workflows/CI.yml)
+      - name: Install TexLive
+        run: sudo apt-get update --fix-missing; sudo apt-get install pdf2svg texlive-latex-base texlive-binaries texlive-pictures texlive-latex-extra texlive-luatex
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: julia --project=docs/ docs/make.jl

README.md

@@ -1,4 +1,6 @@
-# TensorInference
+<p align="center">
+<img width="700px" src="./docs/src/assets/logo-with-name.svg"/>
+</p>
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://TensorBFS.github.io/TensorInference.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://TensorBFS.github.io/TensorInference.jl/dev/)

docs/Project.toml

@@ -3,3 +3,4 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 TensorInference = "c2297e78-99bd-40ad-871d-f50e56b81012"
+TikzPictures = "37f6aa50-8035-52d0-81c2-5a1d08754b2d"

docs/make.jl

@@ -26,15 +26,20 @@ makedocs(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://TensorBFS.github.io/TensorInference.jl",
         edit_link="main",
-        assets=String[],
+        assets = [joinpath("assets", "favicon.ico")],
     ),
     pages=[
         "Home" => "index.md",
+        "Background" => "background.md",
         "Examples" => [
             "Asia network" => "generated/asia/main.md",
            ],
-        "Performance Tips" => "performance.md",
-        "References" => "ref.md",
+        "UAI file formats" => "uai-file-formats.md",
+        "Performance tips" => "performance.md",
+        "API" => [
+          "Public" => "api/public.md",
+          "Internal" => "api/internal.md"
+        ],
     ],
     doctest = false,
 )

docs/src/api/internal.md

@@ -0,0 +1,33 @@
+# Internal API
+
+## Index
+
+[Types](@ref internal_Types)
+
+```@index
+Pages = ["internal.md"]
+Order = [:type]
+```
+
+[Functions](@ref internal_Functions)
+
+```@index
+Pages = ["internal.md"]
+Order = [:function]
+```
+
+## [Types](@id internal_Types)
+
+```@autodocs
+Modules = [TensorInference]
+Order   = [:type]
+Public = false
+```
+
+## [Functions](@id internal_Functions)
+
+```@autodocs
+Modules = [TensorInference]
+Order   = [:function]
+Public = false
+```

docs/src/api/public.md

@@ -0,0 +1,65 @@
+# Public API
+
+## Index
+
+[Modules](@ref)
+
+```@index
+Pages = ["public.md"]
+Order   = [:module]
+```
+
+[Types](@ref)
+
+```@index
+Pages = ["public.md"]
+Order   = [:type]
+```
+
+[Functions](@ref)
+
+```@index
+Pages = ["public.md"]
+Order   = [:function]
+```
+
+## Modules
+
+```@docs
+TensorInference
+```
+
+## Types
+
+```@docs
+GreedyMethod
+KaHyParBipartite
+MergeGreedy
+MergeVectors
+SABipartite
+TreeSA
+MMAPModel
+RescaledArray
+TensorNetworkModel
+UAIInstance
+```
+
+## Functions
+
+```@docs
+contraction_complexity
+get_cards
+get_vars
+log_probability
+marginals
+maximum_logp
+most_probable_config
+probability
+read_evidence_file
+read_instance
+read_model_file
+read_solution_file
+read_td_file
+sample
+set_evidence!
+```