Merge pull request #2057 from recommenders-team/staging

Staging to main: New documentation with Jupyter Book
recommenders-team · Jan 30, 2024 · 310370b · 310370b
2 parents 1d308a4 + 69a485c
commit 310370b
Show file tree

Hide file tree

Showing 30 changed files with 467 additions and 530 deletions.
diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml
@@ -0,0 +1,67 @@
+# ---------------------------------------------------------
+# Copyright (c) Recommenders contributors.
+# Licensed under the MIT License.
+# ---------------------------------------------------------
+
+name: Update Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.10
+
+      - name: Install dependencies
+        run: |
+          pip install -q --upgrade pip setuptools wheel
+          pip install -q --no-use-pep517 lightfm
+          pip install -q .[all]
+          pip install -q -r docs/requirements-doc.txt
+      
+      - name: List dependencies
+        run: |
+          pip list
+
+      - name: Build documentation
+        run: |
+          jupyter-book config sphinx docs/
+          sphinx-build docs docs/_build/html -b html
+
+      - name: Configure Git
+        run: |
+          git config --global user.email "[email protected]"
+          git config --global user.name "GitHub Actions"
+
+      - name: Create and switch to gh-pages branch
+        run: |
+          git checkout -b gh-pages
+          git pull origin gh-pages || true
+      
+      - name: Copy built documentation
+        run: cp -r docs/_build/html/* .
+
+      - name: Add and commit changes
+        run: |
+          git add * -f
+          git commit -m "Update documentation"
+      
+      - name: Configure pull strategy (rebase)
+        run: git config pull.rebase true
+
+      - name: Pull latest changes from remote gh-pages branch
+        run: git pull -Xtheirs origin gh-pages
+
+      - name: Push changes to gh-pages
+        run: git push origin gh-pages
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ Licensed under the MIT License.
 
 # Recommenders
 
-[![Documentation Status](https://readthedocs.org/projects/microsoft-recommenders/badge/?version=latest)](https://microsoft-recommenders.readthedocs.io/en/latest/?badge=latest)
+[![Documentation status](https://github.com/recommenders-team/recommenders/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/recommenders-team/recommenders/actions/workflows/pages/pages-build-deployment)
 
 <img src="https://raw.githubusercontent.com/recommenders-team/artwork/main/color/recommenders_color.svg" width="800">
 
@@ -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
+copyright: "2018-2024"
+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.ext.autodoc
+  - sphinx.ext.doctest
+  - sphinx.ext.intersphinx
+  - sphinx.ext.ifconfig
+  - sphinx.ext.napoleon       # To render Google format docstrings
+  - sphinx.ext.viewcode       # Add links to highlighted source code
+
+
+
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
@@ -75,7 +75,6 @@ this impression. To protect user privacy, each user was de-linked from the produ
     and Ming Zhou, "MIND: A Large-scale Dataset for News Recommendation", ACL, 2020.
 
 
-
 .. automodule:: recommenders.datasets.mind
     :members:  
 
@@ -106,47 +105,41 @@ It comes with several sizes:
 
 Download utilities 
 ******************
-
 .. automodule:: recommenders.datasets.download_utils
     :members:
 
 
-Cosmos CLI utilities
-*********************
-
-.. automodule:: recommenders.datasets.cosmos_cli
-    :members:
-
-
 Pandas dataframe utilities
 ***************************
-
 .. automodule:: recommenders.datasets.pandas_df_utils
     :members:
 
 
 Splitter utilities
 ******************
-
+Python splitters
+================
 .. automodule:: recommenders.datasets.python_splitters
     :members:
 
+PySpark splitters
+=================
 .. automodule:: recommenders.datasets.spark_splitters
     :members:
 
+Other splitters utilities
+=========================
 .. automodule:: recommenders.datasets.split_utils
     :members:
 
 
 Sparse utilities
 ****************
-
 .. automodule:: recommenders.datasets.sparse
     :members:
 
 
 Knowledge graph utilities
 *************************
-
 .. automodule:: recommenders.datasets.wikidata
     :members:
diff --git a/docs/source/evaluation.rst → docs/evaluation.rst b/docs/source/evaluation.rst → docs/evaluation.rst
@@ -13,4 +13,5 @@ PySpark evaluation
 ===============================
 
 .. automodule:: recommenders.evaluation.spark_evaluation
-    :members:
+    :members:
+    :special-members: __init__
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}
+``` -->
+