Skip to content

Commit

Permalink
Merge pull request #2057 from recommenders-team/staging
Browse files Browse the repository at this point in the history
Staging to main: New documentation with Jupyter Book
  • Loading branch information
miguelgfierro authored Jan 30, 2024
2 parents 1d308a4 + 69a485c commit 310370b
Show file tree
Hide file tree
Showing 30 changed files with 467 additions and 530 deletions.
67 changes: 67 additions & 0 deletions .github/workflows/update_documentation.yml
Original file line number Diff line number Diff line change
@@ -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 "actions@github.com"
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
20 changes: 0 additions & 20 deletions .readthedocs.yaml

This file was deleted.

10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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">

Expand All @@ -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/).
Expand Down Expand Up @@ -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 |
|-----------|------|-------------|---------|
Expand Down
19 changes: 0 additions & 19 deletions docs/Makefile

This file was deleted.

18 changes: 0 additions & 18 deletions docs/README.md

This file was deleted.

55 changes: 55 additions & 0 deletions docs/_config.yml
Original file line number Diff line number Diff line change
@@ -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



18 changes: 18 additions & 0 deletions docs/_toc.yml
Original file line number Diff line number Diff line change
@@ -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
19 changes: 6 additions & 13 deletions docs/source/datasets.rst → docs/datasets.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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:
3 changes: 2 additions & 1 deletion docs/source/evaluation.rst → docs/evaluation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,5 @@ PySpark evaluation
===============================

.. automodule:: recommenders.evaluation.spark_evaluation
:members:
:members:
:special-members: __init__
34 changes: 34 additions & 0 deletions docs/intro.md
Original file line number Diff line number Diff line change
@@ -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}
``` -->

Loading

0 comments on commit 310370b

Please sign in to comment.