Improve docs

elixir-nx · Oct 10, 2023 · 31de556 · 31de556
1 parent 07405d6
commit 31de556
Show file tree

Hide file tree

Showing 6 changed files with 31 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -1,7 +1,11 @@
-<h1><img src="./images/scholar.png" alt="Scholar" width="400"></h1>
+<p align="center">
+  <img src="https://github.com/elixir-nx/scholar/raw/main/images/scholar.png" alt="Scholar" width="400">
+  <br />
+  <a href="https://hexdocs.pm/scholar"><img src="http://img.shields.io/badge/hex.pm-docs-green.svg?style=flat" title="Documentation" /></a>
+  <a href="https://hex.pm/packages/scholar"><img src="https://img.shields.io/hexpm/v/scholar.svg" title="Package" /></a>
+</p>
 
-[![Documentation](http://img.shields.io/badge/hex.pm-docs-green.svg?style=flat)](https://hexdocs.pm/scholar)
-[![Package](https://img.shields.io/hexpm/v/scholar.svg)](https://hex.pm/packages/scholar)
+<br />
 
 Traditional machine learning tools built on top of Nx. Scholar implements
 several algorithms for classification, regression, clustering, dimensionality
@@ -45,6 +49,15 @@ config :nx, :default_backend, EXLA.Backend
 config :nx, :default_defn_options, [compiler: EXLA, client: :host]
 ```
 
+> #### JIT required! {: .warning}
+>
+> It is important you set the `default_defn_options` as shown in the snippet above,
+> as many algorithms in Scholar use loops which are much more memory efficient when
+> JIT compiled.
+>
+> If for some reason you cannot set a default `defn` compiler, you can explicitly
+> JIT any function, for example: `EXLA.jit(&Scholar.Cluster.AffinityPropagation.fit/1)`.
+
 ### Notebooks
 
 To use Scholar inside code notebooks, run:
@@ -60,6 +73,15 @@ Nx.global_default_backend(EXLA.Backend)
 Nx.Defn.global_default_options(compiler: EXLA, client: :host)
 ```
 
+> #### JIT required! {: .warning}
+>
+> It is important you set the `Nx.Defn.global_default_options/1` as shown in the snippet
+> above, as many algorithms in Scholar use loops which are much more memory efficient
+> when JIT compiled.
+>
+> If for some reason you cannot set a default `defn` compiler, you can explicitly
+> JIT any function, for example: `EXLA.jit(&Scholar.Cluster.AffinityPropagation.fit/1)`.
+
 ## License
 
 Copyright (c) 2022 The Machine Learning Working Group of the Erlang Ecosystem Foundation

diff --git a/lib/scholar.ex b/lib/scholar.ex
diff --git a/lib/scholar/interpolation/linear.ex b/lib/scholar/interpolation/linear.ex
@@ -20,6 +20,8 @@ defmodule Scholar.Interpolation.Linear do
   @derive {Nx.Container, containers: [:coefficients, :x]}
   defstruct [:coefficients, :x]
 
+  @type t :: %Scholar.Interpolation.Linear{}
+
   @doc """
   Fits a linear interpolation of the given `(x, y)` points
 

diff --git a/lib/scholar/linear/isotonic_regression.ex b/lib/scholar/linear/isotonic_regression.ex
@@ -38,7 +38,7 @@ defmodule Scholar.Linear.IsotonicRegression do
           y_thresholds: Nx.Tensor.t(),
           increasing: Nx.Tensor.t(),
           cutoff_index: Nx.Tensor.t(),
-          preprocess: Tuple.t() | Scholar.Interpolation.Linear.t()
+          preprocess: tuple() | Scholar.Interpolation.Linear.t()
         }
 
   opts = [

diff --git a/mix.exs b/mix.exs
@@ -49,11 +49,12 @@ defmodule Scholar.MixProject do
 
   defp docs do
     [
-      main: "Scholar",
+      main: "readme",
       source_url: @source_url,
       logo: "images/scholar_simplified.png",
       extra_section: "Guides",
       extras: [
+        "README.md",
         "notebooks/linear_regression.livemd",
         "notebooks/k_means.livemd",
         "notebooks/k_nearest_neighbors.livemd",

diff --git a/mix.lock b/mix.lock
@@ -1,6 +1,6 @@
 %{
   "complex": {:hex, :complex, "0.5.0", "af2d2331ff6170b61bb738695e481b27a66780e18763e066ee2cd863d0b1dd92", [:mix], [], "hexpm", "2683bd3c184466cfb94fad74cbfddfaa94b860e27ad4ca1bffe3bff169d91ef1"},
-  "earmark_parser": {:hex, :earmark_parser, "1.4.33", "3c3fd9673bb5dcc9edc28dd90f50c87ce506d1f71b70e3de69aa8154bc695d44", [:mix], [], "hexpm", "2d526833729b59b9fdb85785078697c72ac5e5066350663e5be6a1182da61b8f"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.37", "2ad73550e27c8946648b06905a57e4d454e4d7229c2dafa72a0348c99d8be5f7", [:mix], [], "hexpm", "6b19783f2802f039806f375610faa22da130b8edc21209d0bff47918bb48360e"},
   "elixir_make": {:hex, :elixir_make, "0.7.7", "7128c60c2476019ed978210c245badf08b03dbec4f24d05790ef791da11aa17c", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}], "hexpm", "5bc19fff950fad52bbe5f211b12db9ec82c6b34a9647da0c2224b8b8464c7e6c"},
   "ex_doc": {:hex, :ex_doc, "0.30.6", "5f8b54854b240a2b55c9734c4b1d0dd7bdd41f71a095d42a70445c03cf05a281", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "bd48f2ddacf4e482c727f9293d9498e0881597eae6ddc3d9562bd7923375109f"},
   "exla": {:hex, :exla, "0.6.0", "af63e45ce41ad25630967923147d14292a0cc48e507b8a3cf3bf3d5483099a28", [:make, :mix], [{:elixir_make, "~> 0.6", [hex: :elixir_make, repo: "hexpm", optional: false]}, {:nx, "~> 0.6.0", [hex: :nx, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4.0 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:xla, "~> 0.5.0", [hex: :xla, repo: "hexpm", optional: false]}], "hexpm", "5f6a4a105ea9ab207b9aa4de5a294730e2bfe9639f4b8d37a7c00da131090d7a"},