docs: updated readme and docs

README.md

@@ -30,6 +30,18 @@ The reccomended way to install mlx-optimizers is to install the latest stable re
 pip install mlx-optimizers
 ```
 
+To install mlx-optimizers from source, first clone [the repository](https://github.com/stockeh/mlx-optimizers.git):
+
+```bash
+git clone https://github.com/stockeh/mlx-optimizers.git
+cd mlx-optimizers
+```
+Then run
+
+```bash
+pip install -e .
+```
+
 ## Usage
 
 There are a variety of optimizers to choose from (see [docs](https://stockeh.github.io/mlx-optimizers/build/html/optimizers.html)). Each of these inherit the [`mx.optimizers`](https://ml-explore.github.io/mlx/build/html/python/optimizers.html) class from MLX, so the core functionality remains the same. We can simply use the optimizer as follows:

docs/src/_static/css/custom.css

@@ -0,0 +1,10 @@
+/* CSS to handle image width based on screen size */
+.desktop-width {
+    width: 60%;
+}
+
+@media only screen and (max-width: 768px) {
+    .desktop-width {
+        width: 100%;
+    }
+}

docs/src/conf.py

@@ -5,12 +5,14 @@
 
 sys.path.insert(0, os.path.abspath("../../mlx_optimizers"))
 
+from mlx_optimizers import VERSION
+
 # -- Project information -----------------------------------------------------
 
 project = "mlx-optimizers"
 copyright = "2024, Jason Stock"
 author = "Jason Stock"
-version = "0.1.0"
+version = VERSION
 release = version
 
 # -- General configuration ---------------------------------------------------
@@ -42,6 +44,10 @@
 pygments_style = "sphinx"
 add_module_names = False
 
+html_css_files = [
+    "css/custom.css",
+]
+
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = "sphinx_book_theme"
@@ -57,7 +63,8 @@
     },
 }
 
-html_favicon = html_theme_options["logo"]["image_light"]  # type: ignore
+# html_favicon = html_theme_options["logo"]["image_light"]  # type: ignore
+html_favicon = "_static/favicon.ico"
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -80,7 +87,7 @@ def isfunc(obj):
 
 # -- Options for LaTeX output ------------------------------------------------
 
-latex_documents = [(main_doc, "MLX.tex", "MLX Optimization Documentation", author, "manual")]
+latex_documents = [(main_doc, "MLX.tex", "mlx-optimizers documentation", author, "manual")]
 latex_elements = {
     "preamble": r"""
     \usepackage{enumitem}

docs/src/index.rst

@@ -1,7 +1,32 @@
-MLX Optimizers
-==============
+mlx-optimizers - |version| documentation
+========================================
 
-Talk about MLX here
+A library to experiment with new optimization algorithms in `MLX <https://github.com/ml-explore/mlx>`_. 
+
+* **Diverse Exploration**: includes proven and experimental optimizers like DiffGrad, QHAdam, and others.
+* **Easy Integration**: compatible with MLX for straightforward experimentation and downstream adoption.
+* **Benchmark Examples**: enables quick testing on classic optimization and machine learning tasks.
+
+See a **full list** of optimizers in the :doc:`API Reference <optimizers>`.
+
+.. code-block:: python
+   :caption: Example Usage
+
+      import mlx_optimizers as optim
+
+      #... model, grads, etc.
+      optimizer = optim.DiffGrad(learning_rate=0.001)
+      optimizer.update(model, grads)
+
+.. image:: https://github.com/user-attachments/assets/2ff6430a-dfad-4879-ae39-ec76e2645f21
+   :alt: graph
+   :align: center
+   :class: desktop-width only-dark
+
+.. image:: https://github.com/user-attachments/assets/111f79f2-257e-4a27-8667-3831d233c3b8
+   :alt: graph
+   :align: center
+   :class: desktop-width only-light
 
 .. toctree::
    :caption: Install