(#7) Generate docs from the notebooks.

Author: paveloom

.github/scripts/install-nbconvert.bash

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# A script to install `nbconvert`
+
+# Set auxiliary variables
+# for ANSI escape codes
+cyan="\e[1;36m" # Bold cyan
+reset="\e[0m"   # Reset colors
+
+echo -e "\n${cyan}Upgrading \`pip3\`...${reset}\n"
+pip3 install --upgrade pip
+
+echo -e "\n${cyan}Installing \`nbconvert\`...${reset}\n"
+pip3 install --no-cache-dir nbconvert

.gitignore

@@ -1,5 +1,12 @@
 # User's Makefile
 Makefile
 
+# Project manifests
+*Manifest.toml
+
 # Pictures and plots
-*figures
+*figures
+
+# Directories created when generating documentation
+docs/build
+docs/src/generated

.travis.yml

@@ -0,0 +1,24 @@
+language: julia
+dist: bionic
+
+notifications:
+  email: false
+
+env:
+  global:
+    - PATH=/opt/python/3.8.1/bin:$PATH
+
+branches:
+  only:
+  - notebooks
+
+jobs:
+  include:
+    - name: "Documentation Build, Julia 1.5 (Linux, x64)"
+      julia: 1.5
+      os: linux
+      arch: amd64
+      script:
+        - bash .github/scripts/install-nbconvert.bash
+        - julia --project=docs/ -e 'using Pkg; Pkg.instantiate()'
+        - julia --project=docs docs/make.jl

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/convert.jl

@@ -0,0 +1,97 @@
+# This file contains a script to convert `*.ipynb` files
+# to Markdown files to further transfer to `Documenter`
+
+@info "ConvertScript: converting notebooks to markdown files."
+
+# Get path to the notebooks folder
+notebooks_folder_name = "notebooks"
+notebooks_folder = normpath(joinpath(@__DIR__, "..", notebooks_folder_name))
+
+# Get paths to notebooks and their (base)names
+names = String[]
+notebooks = String[]
+for (root, dirs, files) in walkdir(notebooks_folder)
+    for file in files
+       endswith(file, ".ipynb") && push!(notebooks, joinpath(root, file))
+    end
+end
+names = replace.(basename.(notebooks), ".ipynb" => "")
+
+# Get path to the `make.jl` script
+make = joinpath(@__DIR__, "make.jl")
+
+# Go to the output directory
+generated_folder = joinpath(@__DIR__, "src", "generated")
+output_folder = joinpath(generated_folder, notebooks_folder_name)
+!isdir(generated_folder) && mkdir(generated_folder)
+!isdir(output_folder) && mkdir(output_folder)
+cd(output_folder)
+
+for (index, notebook) in enumerate(notebooks)
+
+    # Get the name of the notebook
+    name = names[index]
+
+    # Go to the folder of the notebook
+    !isdir(name) && mkdir(name)
+    cd(name)
+
+    # Construct the name of a Markdown file
+    md = "$name.md"
+
+    # Convert the notebook to a Markdown file
+    output_cmd_part = ["--output-dir", ".", "--output", "$md", "--log-level", "WARN"]
+    run(`jupyter nbconvert --to markdown $notebook $output_cmd_part`)
+
+    # Get the content of the generated Markdown file
+    lines = readlines("$md")
+
+    # Initialize auxiliary variables
+    inside_julia_block = false
+    inside_output_block = false
+    last_index = size(lines, 1)
+
+    # Put the text output in the text block
+    for (index, line) in enumerate(lines)
+
+        if startswith(line, "```julia") && !inside_julia_block
+            inside_julia_block = true
+            if inside_output_block
+                lines[index - 1] = "```\n"
+                inside_output_block = false
+            end
+            continue
+        elseif startswith(line, "```") && inside_julia_block
+            inside_julia_block = false
+            continue
+        end
+
+        if !inside_output_block && !inside_julia_block  && !isempty(line) #=
+        =# && !startswith(line, "![png]") && !startswith(line, "![svg]")
+            inside_output_block = true
+            lines[index - 1] = "\n```text\n"
+            continue
+        end
+
+        if inside_output_block && index == last_index
+            lines[index] = "\n```"
+        end
+
+    end
+
+    # Construct a meta block to hide the `Edit on GitHub` URL
+    meta_block = join(
+        [
+            "```@meta",
+            "EditURL = \"nothing\"",
+            "```\n\n",
+        ],
+        '\n',
+    )
+
+    open("$md", "w") do io
+        lines[1] = meta_block * lines[1]
+        print(io, join(lines, '\n'))
+    end
+
+end

docs/make.jl

@@ -0,0 +1,44 @@
+using Documenter # A package to manage documentation
+
+# Convert the Jupyter notebooks to Markdown files
+include("convert.jl")
+
+# Create documentation
+makedocs(
+    # Specify a name for the site
+    sitename = "GPKernels",
+
+    # Specify the author
+    authors = "Pavel Sobolev.",
+
+    # Specify the pages on the left side
+    pages = [
+        "Home" => "index.md",
+        "Notebooks" => [
+            "Kernels" => map(
+                s -> "$s" => "generated/$notebooks_folder_name/$s/$s.md", names,
+            ),
+        ],
+    ],
+
+    # Specify a format
+    format = Documenter.HTML(
+        # A fallback for creating docs locally
+        prettyurls = get(ENV, "CI", nothing) == "true"
+    ),
+
+    # Disable doctests
+    doctest = false,
+
+    # Fail if any error occurred
+    strict = true,
+)
+
+# Deploy documentation
+deploydocs(
+    # Specify a repository
+    repo = "github.com/paveloom-c/GPKernels.git",
+
+    # Specify a development branch
+    devbranch = "notebooks",
+)

docs/src/index.md

@@ -0,0 +1,7 @@
+```@meta
+EditURL = "nothing"
+```
+
+# GPKernels
+
+This work is in progress.