Merge branch 'miguel/jupyter_book' into gh-pages

recommenders-team · Dec 31, 2023 · d3aaf39 · d3aaf39
2 parents a001787 + 9ac4744
commit d3aaf39
Show file tree

Hide file tree

Showing 28 changed files with 237 additions and 387 deletions.
diff --git a/README.md b/README.md
@@ -25,10 +25,10 @@ Recommenders is a project under the [Linux Foundation of AI and Data](https://lf
 
 This repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks. The examples detail our learnings on five key tasks:
 
-- [Prepare Data](examples/01_prepare_data): Preparing and loading data for each recommender algorithm.
-- [Model](examples/00_quick_start): Building models using various classical and deep learning recommender algorithms such as Alternating Least Squares ([ALS](https://spark.apache.org/docs/latest/api/python/_modules/pyspark/ml/recommendation.html#ALS)) or eXtreme Deep Factorization Machines ([xDeepFM](https://arxiv.org/abs/1803.05170)).
+- [Prepare Data](examples/01_prepare_data): Preparing and loading data for each recommendation algorithm.
+- [Model](examples/00_quick_start): Building models using various classical and deep learning recommendation algorithms such as Alternating Least Squares ([ALS](https://spark.apache.org/docs/latest/api/python/_modules/pyspark/ml/recommendation.html#ALS)) or eXtreme Deep Factorization Machines ([xDeepFM](https://arxiv.org/abs/1803.05170)).
 - [Evaluate](examples/03_evaluate): Evaluating algorithms with offline metrics.
-- [Model Select and Optimize](examples/04_model_select_and_optimize): Tuning and optimizing hyperparameters for recommender models.
+- [Model Select and Optimize](examples/04_model_select_and_optimize): Tuning and optimizing hyperparameters for recommendation models.
 - [Operationalize](examples/05_operationalize): Operationalizing models in a production environment on Azure.
 
 Several utilities are provided in [recommenders](recommenders) to support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications. See the [Recommenders documentation](https://readthedocs.org/projects/microsoft-recommenders/).
@@ -73,7 +73,7 @@ In addition to the core package, several extras are also provided, including:
 
 ## Algorithms
 
-The table below lists the recommender algorithms currently available in the repository. Notebooks are linked under the Example column as Quick start, showcasing an easy to run example of the algorithm, or as Deep dive, explaining in detail the math and implementation of the algorithm.
+The table below lists the recommendation algorithms currently available in the repository. Notebooks are linked under the Example column as Quick start, showcasing an easy to run example of the algorithm, or as Deep dive, explaining in detail the math and implementation of the algorithm.
 
 | Algorithm | Type | Description | Example |
 |-----------|------|-------------|---------|

diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,55 @@
+# Copyright (c) Recommenders contributors.
+# Licensed under the MIT License.
+
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+# To build the Jupyter Book:
+# $ jupyter-book clean docs 
+# $ jupyter-book build docs
+
+
+title: Recommenders documentation
+author: Recommenders contributors
+logo: https://raw.githubusercontent.com/recommenders-team/artwork/main/color/recommenders_color.svg
+
+
+# Short description about the book
+description: >-
+  Recommenders - Python utilities for building recommendation systems
+
+execute:
+  execute_notebooks           : off
+
+# Interact link settings
+notebook_interface            : "notebook"
+
+# Launch button settings
+repository:
+  url                         : https://github.com/recommenders-team/recommenders 
+  path_to_book                : /docs
+  branch                      : main
+
+launch_buttons:
+  notebook_interface          : classic
+
+# HTML-specific settings
+html:
+  favicon                     : https://raw.githubusercontent.com/recommenders-team/artwork/main/icon/recommenders_color_icon.svg
+  home_page_in_navbar         : false
+  use_repository_button       : true
+  use_issues_button           : true
+  baseurl                     : https://recommenders-team.github.io/recommenders/
+
+sphinx:
+  extra_extensions:
+  - sphinx_inline_tabs
+  - sphinx.ext.autodoc
+  - sphinx.ext.napoleon
+  - sphinx.ext.viewcode
+  config:
+    napoleon_google_docstring: True
+    autodoc_member_order: groupwise
+    autoclass_content: both
+
+
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -0,0 +1,18 @@
+# Copyright (c) Recommenders contributors.
+# Licensed under the MIT License.
+
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+defaults:
+  numbered: false
+parts:
+  - caption: Recommenders API Documentation
+    chapters:
+      - file: datasets
+      - file: evaluation
+      - file: models
+      - file: tuning
+      - file: utils
diff --git a/docs/source/datasets.rst → docs/datasets.rst b/docs/source/datasets.rst → docs/datasets.rst
@@ -111,13 +111,6 @@ Download utilities
     :members:
 
 
-Cosmos CLI utilities
-*********************
-
-.. automodule:: recommenders.datasets.cosmos_cli
-    :members:
-
-
 Pandas dataframe utilities
 ***************************
 

diff --git a/docs/source/evaluation.rst → docs/evaluation.rst b/docs/source/evaluation.rst → docs/evaluation.rst
diff --git a/docs/intro.md b/docs/intro.md
@@ -0,0 +1,34 @@
+<!--
+Copyright (c) Recommenders contributors.
+Licensed under the MIT License.
+-->
+
+# Welcome to Recommenders
+
+Recommenders objective is to assist researchers, developers and enthusiasts in prototyping, experimenting with and bringing to production a range of classic and state-of-the-art recommendation systems.
+
+````{margin}
+```sh
+pip install recommenders
+```
+<a class="github-button" href="https://github.com/recommenders-team/recommenders" data-icon="octicon-star" style="margin:auto" data-size="large" data-show-count="true" aria-label="Star Recommenders on GitHub">Star Us</a><script async defer src="https://buttons.github.io/buttons.js"></script>
+````
+
+Recommenders is a project under the [Linux Foundation of AI and Data](https://lfaidata.foundation/projects/). 
+
+This repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks.
+
+The examples detail our learnings on five key tasks:
+
+- Prepare Data: Preparing and loading data for each recommendation algorithm.
+- Model: Building models using various classical and deep learning recommendation algorithms such as Alternating Least Squares ([ALS](https://spark.apache.org/docs/latest/api/python/_modules/pyspark/ml/recommendation.html#ALS)) or eXtreme Deep Factorization Machines ([xDeepFM](https://arxiv.org/abs/1803.05170)).
+- Evaluate: Evaluating algorithms with offline metrics.
+- Model Select and Optimize: Tuning and optimizing hyperparameters for recommendation models.
+- Operationalize: Operationalizing models in a production environment.
+
+Several utilities are provided in the `recommenders` library to support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications.
+
+
+<!-- ```{tableofcontents}
+``` -->
+
diff --git a/docs/source/models.rst → docs/models.rst b/docs/source/models.rst → docs/models.rst
@@ -29,16 +29,16 @@ DKN item-to-item
 .. automodule:: recommenders.models.deeprec.models.dkn_item2item
     :members:
 
-LightGCN
-==================
-.. automodule:: recommenders.models.deeprec.models.graphrec.lightgcn
-    :members:
-
 xDeepFM
 ==============
 .. automodule:: recommenders.models.deeprec.models.xDeepFM
     :members:
 
+LightGCN
+==================
+.. automodule:: recommenders.models.deeprec.models.graphrec.lightgcn
+    :members:
+
 Sequential models
 ==================
 
@@ -257,6 +257,13 @@ VAE
     :members:
 
 
+Vowpal Wabbit
+******************************
+
+.. automodule:: recommenders.models.vowpal_wabbit.vw
+    :members:
+
+
 Wide & Deep
 ******************************
 

diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt
@@ -0,0 +1,4 @@
+jupyter-book
+sphinx
+sphinx_inline_tabs
+ghp-import