Skip to content

Commit 69a485c

Browse files
miguelgfierromiguelgfierro
authored
Merge pull request #2051 from recommenders-team/miguel/jupyter_book
New documentation with Jupyter book
2 parents b184e44 + 1aa1945 commit 69a485c

30 files changed

+467
-530
lines changed

‎.github/workflows/update_documentation.yml

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# ---------------------------------------------------------
2+
# Copyright (c) Recommenders contributors.
3+
# Licensed under the MIT License.
4+
# ---------------------------------------------------------
5+
6+
name: Update Documentation
7+
8+
on:
9+
push:
10+
branches:
11+
- main
12+
13+
jobs:
14+
build:
15+
runs-on: ubuntu-22.04
16+
17+
steps:
18+
- name: Checkout repository
19+
uses: actions/checkout@v3
20+
21+
- name: Set up Python
22+
uses: actions/setup-python@v4
23+
with:
24+
python-version: 3.10
25+
26+
- name: Install dependencies
27+
run: |
28+
pip install -q --upgrade pip setuptools wheel
29+
pip install -q --no-use-pep517 lightfm
30+
pip install -q .[all]
31+
pip install -q -r docs/requirements-doc.txt
32+
33+
- name: List dependencies
34+
run: |
35+
pip list
36+
37+
- name: Build documentation
38+
run: |
39+
jupyter-book config sphinx docs/
40+
sphinx-build docs docs/_build/html -b html
41+
42+
- name: Configure Git
43+
run: |
44+
git config --global user.email "[email protected]"
45+
git config --global user.name "GitHub Actions"
46+
47+
- name: Create and switch to gh-pages branch
48+
run: |
49+
git checkout -b gh-pages
50+
git pull origin gh-pages || true
51+
52+
- name: Copy built documentation
53+
run: cp -r docs/_build/html/* .
54+
55+
- name: Add and commit changes
56+
run: |
57+
git add * -f
58+
git commit -m "Update documentation"
59+
60+
- name: Configure pull strategy (rebase)
61+
run: git config pull.rebase true
62+
63+
- name: Pull latest changes from remote gh-pages branch
64+
run: git pull -Xtheirs origin gh-pages
65+
66+
- name: Push changes to gh-pages
67+
run: git push origin gh-pages

‎.readthedocs.yaml

-20
This file was deleted.

‎README.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Licensed under the MIT License.
55

66
# Recommenders
77

8-
[![Documentation Status](https://readthedocs.org/projects/microsoft-recommenders/badge/?version=latest)](https://microsoft-recommenders.readthedocs.io/en/latest/?badge=latest)
8+
[![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)
99

1010
<img src="https://raw.githubusercontent.com/recommenders-team/artwork/main/color/recommenders_color.svg" width="800">
1111

@@ -25,10 +25,10 @@ Recommenders is a project under the [Linux Foundation of AI and Data](https://lf
2525

2626
This repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks. The examples detail our learnings on five key tasks:
2727

28-
- [Prepare Data](examples/01_prepare_data): Preparing and loading data for each recommender algorithm.
29-
- [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)).
28+
- [Prepare Data](examples/01_prepare_data): Preparing and loading data for each recommendation algorithm.
29+
- [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)).
3030
- [Evaluate](examples/03_evaluate): Evaluating algorithms with offline metrics.
31-
- [Model Select and Optimize](examples/04_model_select_and_optimize): Tuning and optimizing hyperparameters for recommender models.
31+
- [Model Select and Optimize](examples/04_model_select_and_optimize): Tuning and optimizing hyperparameters for recommendation models.
3232
- [Operationalize](examples/05_operationalize): Operationalizing models in a production environment on Azure.
3333

3434
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:
7373

7474
## Algorithms
7575

76-
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.
76+
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.
7777

7878
| Algorithm | Type | Description | Example |
7979
|-----------|------|-------------|---------|

‎docs/Makefile

-19
This file was deleted.

‎docs/README.md

-18
This file was deleted.

‎docs/_config.yml

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Copyright (c) Recommenders contributors.
2+
# Licensed under the MIT License.
3+
4+
# Book settings
5+
# Learn more at https://jupyterbook.org/customize/config.html
6+
7+
# To build the Jupyter Book:
8+
# $ jupyter-book clean docs
9+
# $ jupyter-book build docs
10+
11+
12+
title: Recommenders documentation
13+
author: Recommenders contributors
14+
copyright: "2018-2024"
15+
logo: https://raw.githubusercontent.com/recommenders-team/artwork/main/color/recommenders_color.svg
16+
17+
18+
# Short description about the book
19+
description: >-
20+
Recommenders - Python utilities for building recommendation systems
21+
22+
execute:
23+
execute_notebooks : off
24+
25+
# Interact link settings
26+
notebook_interface : "notebook"
27+
28+
# Launch button settings
29+
repository:
30+
url : https://github.com/recommenders-team/recommenders
31+
path_to_book : /docs
32+
branch : main
33+
34+
launch_buttons:
35+
notebook_interface : classic
36+
37+
# HTML-specific settings
38+
html:
39+
favicon : https://raw.githubusercontent.com/recommenders-team/artwork/main/icon/recommenders_color_icon.svg
40+
home_page_in_navbar : false
41+
use_repository_button : true
42+
use_issues_button : true
43+
baseurl : https://recommenders-team.github.io/recommenders/
44+
45+
sphinx:
46+
extra_extensions:
47+
- sphinx.ext.autodoc
48+
- sphinx.ext.doctest
49+
- sphinx.ext.intersphinx
50+
- sphinx.ext.ifconfig
51+
- sphinx.ext.napoleon # To render Google format docstrings
52+
- sphinx.ext.viewcode # Add links to highlighted source code
53+
54+
55+

‎docs/_toc.yml

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Copyright (c) Recommenders contributors.
2+
# Licensed under the MIT License.
3+
4+
# Table of contents
5+
# Learn more at https://jupyterbook.org/customize/toc.html
6+
7+
format: jb-book
8+
root: intro
9+
defaults:
10+
numbered: false
11+
parts:
12+
- caption: Recommenders API Documentation
13+
chapters:
14+
- file: datasets
15+
- file: evaluation
16+
- file: models
17+
- file: tuning
18+
- file: utils

‎docs/source/datasets.rst ‎docs/datasets.rst

+6-13
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,6 @@ this impression. To protect user privacy, each user was de-linked from the produ
7575
and Ming Zhou, "MIND: A Large-scale Dataset for News Recommendation", ACL, 2020.
7676

7777

78-
7978
.. automodule:: recommenders.datasets.mind
8079
:members:
8180

@@ -106,47 +105,41 @@ It comes with several sizes:
106105

107106
Download utilities
108107
******************
109-
110108
.. automodule:: recommenders.datasets.download_utils
111109
:members:
112110

113111

114-
Cosmos CLI utilities
115-
*********************
116-
117-
.. automodule:: recommenders.datasets.cosmos_cli
118-
:members:
119-
120-
121112
Pandas dataframe utilities
122113
***************************
123-
124114
.. automodule:: recommenders.datasets.pandas_df_utils
125115
:members:
126116

127117

128118
Splitter utilities
129119
******************
130-
120+
Python splitters
121+
================
131122
.. automodule:: recommenders.datasets.python_splitters
132123
:members:
133124

125+
PySpark splitters
126+
=================
134127
.. automodule:: recommenders.datasets.spark_splitters
135128
:members:
136129

130+
Other splitters utilities
131+
=========================
137132
.. automodule:: recommenders.datasets.split_utils
138133
:members:
139134

140135

141136
Sparse utilities
142137
****************
143-
144138
.. automodule:: recommenders.datasets.sparse
145139
:members:
146140

147141

148142
Knowledge graph utilities
149143
*************************
150-
151144
.. automodule:: recommenders.datasets.wikidata
152145
:members:

‎docs/source/evaluation.rst ‎docs/evaluation.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@ PySpark evaluation
1313
===============================
1414

1515
.. automodule:: recommenders.evaluation.spark_evaluation
16-
:members:
16+
:members:
17+
:special-members: __init__

‎docs/intro.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<!--
2+
Copyright (c) Recommenders contributors.
3+
Licensed under the MIT License.
4+
-->
5+
6+
# Welcome to Recommenders
7+
8+
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.
9+
10+
````{margin}
11+
```sh
12+
pip install recommenders
13+
```
14+
<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>
15+
````
16+
17+
Recommenders is a project under the [Linux Foundation of AI and Data](https://lfaidata.foundation/projects/).
18+
19+
This repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks.
20+
21+
The examples detail our learnings on five key tasks:
22+
23+
- Prepare Data: Preparing and loading data for each recommendation algorithm.
24+
- 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)).
25+
- Evaluate: Evaluating algorithms with offline metrics.
26+
- Model Select and Optimize: Tuning and optimizing hyperparameters for recommendation models.
27+
- Operationalize: Operationalizing models in a production environment.
28+
29+
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.
30+
31+
32+
<!-- ```{tableofcontents}
33+
``` -->
34+

0 commit comments

Comments
 (0)