Documenting Fastmath in Clay

Introduction

We are documenting all of the functions in Fastmath using Clay (Quarto) book replacing all existing pieces in Codox, Metadoc and Clerk. We document 3.x version (3.x branch).

Cloning

git clone --recurse-submodules [email protected]:generateme/fastmath.git
git checkout 3.x

Prerequisites

To work on documentation you have to install locally:

• Quarto (see more about the setup here)
• R (see more about the setup here)

Quarto is used to build documentation in a book format. R with ggplot2 to render charts.

R and clojisr

You need to install some R packages to make it work:

install.packages(c("tidyverse","svglite"), dependencies=T)
install.packages("Rserve",,"http://rforge.net")

Goals

By creating a documentation in Clay, we want to:

• Build consistent documentation based on logical structure + docstrings
• Add more use cases and give good examples for more complicated functions
• Perform sanity test of fastmath
• Illustrate examples with charts, formulas
• Describe pitfalls

Source

The source of the book is in the clay folder. Code used in generating the book is located in utils/fastmath/dev folder and contains (currently) three namespaces:

• fastmath/dev/clay - building a book, examples/callouts/tables helpers
• fastmath/dev/ggplot - charts
• fastmath/dev/codox - reference in the Codox style

Building

To build whole book call a code snippet defined in utils/fastmath/dev/clay.clj

Target folder is: docs/clay

Chapters

General structure of the chapter looks like the following example which contains all elements used in documentation:

^:kindly/hide-code
(ns transform
  (:require [fastmath.transform :as t]

            [fastmath.dev.ggplot :as gg]
            [fastmath.dev.clay :as utls]
            [fastmath.dev.codox :as codox]

            [fastmath.core :as m]))

;; # Transforms {.unnumbered}

;; General description of the topic

;; ::: {.callout-tip title="Defined functions"}
;; * `transformer`
;; * `forward-1d`, `forward-2d`
;; * `reverse-1d`, `reverse-2d`
;; :::

;; ## FFT

;; Details about FFT and use-cases

;; Some examples:

(def fft-real (t/transformer :real :fft ))

(utls/examples-note
  (seq (t/forward-1d fft-real [1 2 -10 1]))
  (seq (t/reverse-1d fft-real [-6 -12 11 -1])))

;; ## Wavelets

;; ## Compression and denoising

;; An use case with charts

(def domain (m/slice-range 0 10 512))
(def signal (map (fn [x] (+ (Math/sin x)
                         (* 0.1 (- (rand) 0.5)))) ;; add some noise
               domain))
(def denoised-signal (t/denoise fft-real signal {:method :hard}))

^:kind/table
[[(gg/->image (gg/line domain signal {:title "Original signal"}))
  (gg/->image (gg/line domain denoised-signal {:title "Denoised signal"}))]]

;; ## Reference

(codox/make-public-fns-table-clay 'fastmath.transform)

Charts

Charts are created with ggplot2 R package, however ready to use Clojure charting functions are defined in fastmath.dev.ggplot namespace.

Common options

Most charts accept following common options:

• :title - chart title
• :xlab - x-axis label
• :ylab - y-axis label
• :xlim - limit x axis
• :ylim - limit y axis

File or image

There are two helper functions:

• ->file - save chart to a file (default: img.png)
• ->image - create BufferedImage which will be embedded in the notebook

Function

(function fn options)

where options include:

• :x - domain
• :steps - number of sampled values
• :color - line color

(gg/->file (gg/function m/tan {:x [m/-TWO_PI m/TWO_PI]
                               :title "tan(x)"
                               :ylab "y=tan(x)"
                               :ylim [-2 2] ;; we need to limit y axis
                               :steps 500}))

Functions

Multiple functions in one chart with a legend

Funtion 2d

Lollipop

Line

Scatter

Colors and palettes

We use the following colors and palettes:

• color-main - default dark blue color
• color-light - light blue
• palette-blue-0 - blue palette with first color set to color-main
• palette-blue-1 - only color-main, used for functions chart where lines have different styles (dotted/dashed)

Codox

Codox documentation is generated by make-public-fns-table-clay function for given namespace symbol. Use it at the end of the notebook in a reference chapter.