Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Staging to main: New documentation with Jupyter Book #2057

Merged
merged 50 commits into from
Jan 30, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
50 commits
Select commit Hold shift + click to select a range
28701df
Creating a jupyter book
miguelgfierro Dec 27, 2023
9474dff
Creating documentation
miguelgfierro Dec 27, 2023
6028199
:memo:
miguelgfierro Dec 28, 2023
9b95db3
WIP
miguelgfierro Dec 29, 2023
2b7a4c0
Added rst files
miguelgfierro Dec 29, 2023
4dd2277
license
miguelgfierro Dec 29, 2023
b45c3b0
Weird warning with a link in the docstrings
miguelgfierro Dec 29, 2023
7f32281
:memo:
miguelgfierro Dec 30, 2023
9e6f48f
Fix docstring errors and replace .. note:: with Note:
miguelgfierro Dec 30, 2023
c5a0a12
:memo:
miguelgfierro Dec 30, 2023
0467655
:memo:
miguelgfierro Dec 30, 2023
b887e43
Automatic build of documentation
miguelgfierro Dec 31, 2023
8722550
Automatic build of documentation dev
miguelgfierro Dec 31, 2023
20720f5
Automatic build of documentation deps
miguelgfierro Dec 31, 2023
23fa87c
Automatic build of documentation deps
miguelgfierro Dec 31, 2023
42cd152
Automatic build of documentation deps
miguelgfierro Dec 31, 2023
9ac4744
Delete workflow and try via UI
miguelgfierro Dec 31, 2023
020e497
Added again the workflow
miguelgfierro Dec 31, 2023
48b7cbc
git add * -rf
miguelgfierro Dec 31, 2023
e5b9fb9
git add * -f
miguelgfierro Dec 31, 2023
ea93f7b
add git info
miguelgfierro Dec 31, 2023
006a33d
actions to automatically update documentation
miguelgfierro Jan 4, 2024
9263c7d
actions to automatically update documentation
miguelgfierro Jan 4, 2024
5a221df
actions to automatically update documentation :bug:
miguelgfierro Jan 4, 2024
b3217f8
actions to automatically update documentation :bug:
miguelgfierro Jan 4, 2024
4809321
trying github token
miguelgfierro Jan 4, 2024
6d12b5b
trying github token
miguelgfierro Jan 4, 2024
5d75e4e
trying github token and pull before pushing
miguelgfierro Jan 4, 2024
ee00e7e
pull rebase
miguelgfierro Jan 4, 2024
9af8f1a
pull rebase and -Xtheirs
miguelgfierro Jan 4, 2024
45919f2
clean
miguelgfierro Jan 4, 2024
7699008
Update documentation badge
miguelgfierro Jan 4, 2024
4b2bba8
install all deps
miguelgfierro Jan 4, 2024
1abc9a6
try adding other sphinx extensions
miguelgfierro Jan 4, 2024
5bea29b
Refact model rst
miguelgfierro Jan 5, 2024
072c6bd
comment geoimc and rlrmc docs until issue is fixed
miguelgfierro Jan 5, 2024
a8f0614
:memo:
miguelgfierro Jan 5, 2024
bb38687
Adding init and other special members
miguelgfierro Jan 5, 2024
9952f1c
Adding init and other special members
miguelgfierro Jan 5, 2024
ee60873
Reviewing other rst
miguelgfierro Jan 5, 2024
f892bf0
Change sphinx version
miguelgfierro Jan 15, 2024
e67715d
Change sphinx version and jupyter book
miguelgfierro Jan 15, 2024
32ee9d8
Change the way we compile the documentation
miguelgfierro Jan 15, 2024
6dcfdb1
Using the latest JB release
miguelgfierro Jan 27, 2024
d090846
Documentation working
miguelgfierro Jan 27, 2024
126b942
Update docs/_config.yml
miguelgfierro Jan 29, 2024
76e5648
Update docs/requirements-doc.txt
miguelgfierro Jan 29, 2024
972f095
Update docs/_config.yml
miguelgfierro Jan 29, 2024
1aa1945
Added comments by @SimonYansenZhao
miguelgfierro Jan 29, 2024
69a485c
Merge pull request #2051 from recommenders-team/miguel/jupyter_book
miguelgfierro Jan 29, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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 "[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
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
Loading