Skip to content

Commit 729da27

Browse files
oliverholworthyedknv
oliverholworthy
and
edknv
authored
Build docs for stable branch and make default (#1116)
* Update Merlin links to main to stable branch * Match only release tags for docs builds * Setup local branches for docs multi build * Setup docs redirect page to link to stable branch * Remove stable reference from docs link in readme (rely on redirect) --------- Co-authored-by: edknv <109497216+edknv@users.noreply.github.com>
1 parent cba6697 commit 729da27

21 files changed

+78
-72
lines changed

‎.github/workflows/docs-sched-rebuild.yaml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@ jobs:
2626
- name: Install dependencies
2727
run: |
2828
python -m pip install --upgrade pip tox
29+
- name: Setup local branches for docs build
30+
run: |
31+
git branch --track main origin/main || true
32+
git branch --track stable origin/stable || true
2933
- name: Building docs (multiversion)
3034
run: |
3135
tox -vv -e docs-multi
@@ -83,7 +87,7 @@ jobs:
8387
exit 0
8488
fi
8589
# If any of these commands fail, fail the build.
86-
def_branch=$(gh api "repos/${GITHUB_REPOSITORY}" --jq ".default_branch")
90+
def_branch="stable"
8791
html_url=$(gh api "repos/${GITHUB_REPOSITORY}/pages" --jq ".html_url")
8892
cat > index.html << EOF
8993
<!DOCTYPE html>

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ into three categories:
2323

2424
### Your first issue
2525

26-
1. Read the project's [README.md](https://github.com/NVIDIA-Merlin/models/blob/main/README.md)
26+
1. Read the project's [README.md](https://github.com/NVIDIA-Merlin/models/blob/stable/README.md)
2727
to learn how to setup the development environment.
2828
2. Find an issue to work on. The best way is to look for the [good first issue](https://github.com/NVIDIA-Merlin/models/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
2929
or [help wanted](https://github.com/NVIDIA-Merlin/models/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) labels.
@@ -116,7 +116,7 @@ deep_block: Block
116116
```
117117

118118
The [Intersphinx](https://docs.readthedocs.io/en/stable/guides/intersphinx.html)
119-
extension truncates the text to [Schema](https://nvidia-merlin.github.io/core/main/api/merlin.schema.html)
119+
extension truncates the text to [Schema](https://nvidia-merlin.github.io/core/stable/api/merlin.schema.html)
120120
and makes it a link.
121121

122122
## Attribution

‎README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![PyPI version shields.io](https://img.shields.io/pypi/v/merlin-models.svg)](https://pypi.python.org/pypi/merlin-models/)
44
![GitHub License](https://img.shields.io/github/license/NVIDIA-Merlin/models)
5-
[![Documentation](https://img.shields.io/badge/documentation-blue.svg)](https://nvidia-merlin.github.io/models/main/)
5+
[![Documentation](https://img.shields.io/badge/documentation-blue.svg)](https://nvidia-merlin.github.io/models/)
66

77
The Merlin Models library provides standard models for recommender systems with an aim for high-quality implementations
88
that range from classic machine learning models to highly-advanced deep learning models.
@@ -17,7 +17,7 @@ In our initial releases, Merlin Models features a TensorFlow API. The PyTorch AP
1717

1818
### Benefits of Merlin Models
1919

20-
**[RecSys model implementations](https://nvidia-merlin.github.io/models/main/models_overview.html)** - The library provides a high-level API for classic and state-of-the-art deep learning architectures for recommender models.
20+
**[RecSys model implementations](https://nvidia-merlin.github.io/models/stable/models_overview.html)** - The library provides a high-level API for classic and state-of-the-art deep learning architectures for recommender models.
2121
These models include both retrieval (e.g. Matrix Factorization, Two tower, YouTube DNN, ..) and ranking (e.g. DLRM, DCN-v2, DeepFM, ...) models.
2222

2323
**Building blocks** - Within Merlin Models, recommender models are built on reusable building blocks.
@@ -28,7 +28,7 @@ The library provides model definition blocks (MLP layers, factorization layers,
2828
For example, models depend on NVTabular for pre-processing and integrate easily with Merlin Systems for inference.
2929
The thoughtfully-designed integration makes it straightforward to build performant end-to-end RecSys pipelines.
3030

31-
**[Merlin Models DataLoaders](https://nvidia-merlin.github.io/models/main/api.html#loader-utility-functions)** - Merlin provides seamless integration with common deep learning frameworks, such as TensorFlow, PyTorch, and HugeCTR.
31+
**[Merlin Models DataLoaders](https://nvidia-merlin.github.io/models/stable/api.html#loader-utility-functions)** - Merlin provides seamless integration with common deep learning frameworks, such as TensorFlow, PyTorch, and HugeCTR.
3232
When training deep learning recommender system models, data loading can be a bottleneck.
3333
To address the challenge, Merlin has custom, highly-optimized dataloaders to accelerate existing TensorFlow and PyTorch training pipelines.
3434
The Merlin dataloaders can lead to a speedup that is nine times faster than the same training pipeline used with the GPU.
@@ -40,7 +40,7 @@ With the Merlin dataloaders, you can:
4040
- Prepare batches asynchronously into the GPU to avoid CPU-to-GPU communication.
4141
- Integrate easily into existing TensorFlow or PyTorch training pipelines by using a similar API.
4242

43-
To learn about the core features of Merlin Models, see the [Models Overview](https://nvidia-merlin.github.io/models/main/models_overview.html) page.
43+
To learn about the core features of Merlin Models, see the [Models Overview](https://nvidia-merlin.github.io/models/stable/models_overview.html) page.
4444

4545
### Installation
4646

@@ -59,7 +59,7 @@ pip install merlin-models
5959

6060
Merlin Models is included in the Merlin Containers.
6161

62-
Refer to the [Merlin Containers](https://nvidia-merlin.github.io/Merlin/main/containers.html) documentation page for information about the Merlin container names, URLs to the container images on the NVIDIA GPU Cloud catalog, and key Merlin components.
62+
Refer to the [Merlin Containers](https://nvidia-merlin.github.io/Merlin/stable/containers.html) documentation page for information about the Merlin container names, URLs to the container images on the NVIDIA GPU Cloud catalog, and key Merlin components.
6363

6464
#### Installing Merlin Models from Source
6565

@@ -75,7 +75,7 @@ cd models && pip install -e .
7575
Merlin Models makes it straightforward to define architectures that adapt to different input features.
7676
This adaptability is provided by building on a core feature of the NVTabular library.
7777
When you use NVTabular for feature engineering, NVTabular creates a schema that identifies the input features.
78-
You can see the `Schema` object in action by looking at the [From ETL to Training RecSys models - NVTabular and Merlin Models integrated example](https://nvidia-merlin.github.io/models/main/examples/02-Merlin-Models-and-NVTabular-integration.html) example notebook.
78+
You can see the `Schema` object in action by looking at the [From ETL to Training RecSys models - NVTabular and Merlin Models integrated example](https://nvidia-merlin.github.io/models/stable/examples/02-Merlin-Models-and-NVTabular-integration.html) example notebook.
7979

8080
You can easily build popular RecSys architectures like [DLRM](http://arxiv.org/abs/1906.00091), as shown in the following code sample.
8181
After you define the model, you can train and evaluate it with a typical Keras model.
@@ -107,11 +107,11 @@ eval_metrics = model.evaluate(valid, batch_size=1024, return_dict=True)
107107
The target binary feature is also inferred from the schema (i.e., tagged as 'TARGET').
108108

109109
You can find more details and information about a low-level API in our overview of the
110-
[Deep Learning Recommender Model](https://nvidia-merlin.github.io/models/main/models_overview.html#deep-learning-recommender-model).
110+
[Deep Learning Recommender Model](https://nvidia-merlin.github.io/models/stable/models_overview.html#deep-learning-recommender-model).
111111

112112
### Notebook Examples and Tutorials
113113

114-
View the example notebooks in the [documentation](https://nvidia-merlin.github.io/models/main/examples/README.html) to help you become familiar with Merlin Models.
114+
View the example notebooks in the [documentation](https://nvidia-merlin.github.io/models/stable/examples/README.html) to help you become familiar with Merlin Models.
115115

116116
The same notebooks are available in the `examples` directory from the [Merlin Models](https://github.com/NVIDIA-Merlin/models) GitHub repository.
117117

‎docs/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ the link is to the repository:
102102

103103
```markdown
104104
Refer to the sample Python programs in the
105-
[examples/blah](https://github.com/NVIDIA-Merlin/models/tree/main/examples/blah)
105+
[examples/blah](https://github.com/NVIDIA-Merlin/models/tree/stable/examples/blah)
106106
directory of the repository.
107107
```
108108

@@ -139,7 +139,7 @@ a relative path works both in the HTML docs page and in the repository browsing
139139
Use a link to the HTML page like the following:
140140

141141
```markdown
142-
<https://nvidia-merlin.github.io/NVTabular/main/Introduction.html>
142+
<https://nvidia-merlin.github.io/NVTabular/stable/Introduction.html>
143143
```
144144

145145
> I'd like to change this in the future. My preference would be to use a relative

‎docs/source/conf.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
# documentation root, use os.path.abspath to make it absolute, like shown here.
2828
#
2929
import os
30+
import re
3031
import subprocess
3132
import sys
3233

@@ -115,24 +116,25 @@
115116

116117
if os.path.exists(gitdir):
117118
tag_refs = subprocess.check_output(["git", "tag", "-l", "v*"]).decode("utf-8").split()
119+
tag_refs = [tag for tag in tag_refs if re.match(r"^v[0-9]+.[0-9]+.[0-9]+$", tag)]
118120
tag_refs = natsorted(tag_refs)[-6:]
119121
smv_tag_whitelist = r"^(" + r"|".join(tag_refs) + r")$"
120122
else:
121123
smv_tag_whitelist = r"^v.*$"
122124

123-
smv_branch_whitelist = r"^main$"
125+
smv_branch_whitelist = r"^(main|stable)$"
124126

125127
smv_refs_override_suffix = r"-docs"
126128

127129
html_sidebars = {"**": ["versions.html"]}
128-
html_baseurl = "https://nvidia-merlin.github.io/models/main"
130+
html_baseurl = "https://nvidia-merlin.github.io/models/stable/"
129131

130132
intersphinx_mapping = {
131133
"python": ("https://docs.python.org/3", None),
132134
"cudf": ("https://docs.rapids.ai/api/cudf/stable/", None),
133135
"distributed": ("https://distributed.dask.org/en/latest/", None),
134136
"torch": ("https://pytorch.org/docs/stable/", None),
135-
"merlin-core": ("https://nvidia-merlin.github.io/core/main/", None),
137+
"merlin-core": ("https://nvidia-merlin.github.io/core/stable/", None),
136138
}
137139

138140
autodoc_inherit_docstrings = False

‎docs/source/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Merlin Models GitHub Repository
1515

1616
About Merlin
1717
Merlin is the overarching project that brings together the Merlin projects.
18-
See the `documentation <https://nvidia-merlin.github.io/Merlin/main/README.html>`_
18+
See the `documentation <https://nvidia-merlin.github.io/Merlin/stable/README.html>`_
1919
or the `repository <https://github.com/NVIDIA-Merlin/Merlin>`_ on GitHub.
2020

2121
Developer website for Merlin

‎examples/02-Merlin-Models-and-NVTabular-integration.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1409,7 +1409,7 @@
14091409
"\n",
14101410
"In the next notebooks, we will explore multiple ranking models with Merlin Models.\n",
14111411
"\n",
1412-
"You can learn more about NVTabular, its functionality and supported ops by visiting our [github repository](https://github.com/NVIDIA-Merlin/NVTabular/) or exploring the [examples](https://github.com/NVIDIA-Merlin/NVTabular/tree/main/examples), such as [`Getting Started MovieLens`](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/examples/getting-started-movielens/02-ETL-with-NVTabular.ipynb) or [`Scaling Criteo`](https://github.com/NVIDIA-Merlin/NVTabular/tree/main/examples/scaling-criteo)."
1412+
"You can learn more about NVTabular, its functionality and supported ops by visiting our [github repository](https://github.com/NVIDIA-Merlin/NVTabular/) or exploring the [examples](https://github.com/NVIDIA-Merlin/NVTabular/tree/stable/examples), such as [`Getting Started MovieLens`](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/examples/getting-started-movielens/02-ETL-with-NVTabular.ipynb) or [`Scaling Criteo`](https://github.com/NVIDIA-Merlin/NVTabular/tree/stable/examples/scaling-criteo)."
14131413
]
14141414
}
14151415
],

‎examples/03-Exploring-different-models.ipynb‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@
4747
"\n",
4848
"In this example, we'll demonstrate how to build and train several popular deep learning-based ranking model architectures. Merlin Models provides a high-level API to define those architectures, but allows for customization as they are composed by reusable building blocks.\n",
4949
"\n",
50-
"In this example notebook, we use for training and evaluation synthetic data that mimics the schema (features and cardinalities) of [Ali-CCP dataset](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1): Alibaba Click and Conversion Prediction dataset. The Ali-CCP is a dataset gathered from real-world traffic logs of the recommender system in Taobao, the largest online retail platform in the world. To download the raw Ali-CCP training and test datasets visit [tianchi.aliyun.com](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1). You can get the raw dataset via this [get_aliccp() function](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/datasets/ecommerce/aliccp/dataset.py#L43) and generate the parquet files from it to be used in this example.\n",
50+
"In this example notebook, we use for training and evaluation synthetic data that mimics the schema (features and cardinalities) of [Ali-CCP dataset](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1): Alibaba Click and Conversion Prediction dataset. The Ali-CCP is a dataset gathered from real-world traffic logs of the recommender system in Taobao, the largest online retail platform in the world. To download the raw Ali-CCP training and test datasets visit [tianchi.aliyun.com](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1). You can get the raw dataset via this [get_aliccp() function](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/datasets/ecommerce/aliccp/dataset.py#L43) and generate the parquet files from it to be used in this example.\n",
5151
"\n",
5252
"### Learning objectives\n",
5353
"- Preparing the data with NVTabular\n",
@@ -432,7 +432,7 @@
432432
}
433433
},
434434
"source": [
435-
"We're ready to start training, for that, we create our dataset objects, and under the hood we use Merlin `Loader` class for reading chunks of parquet files. `Loader` asynchronously iterate through CSV or Parquet dataframes on GPU by leveraging an NVTabular `Dataset`. To read more about Merlin optimized dataloaders visit [here](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/dataset.py#L141)."
435+
"We're ready to start training, for that, we create our dataset objects, and under the hood we use Merlin `Loader` class for reading chunks of parquet files. `Loader` asynchronously iterate through CSV or Parquet dataframes on GPU by leveraging an NVTabular `Dataset`. To read more about Merlin optimized dataloaders visit [here](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/dataset.py#L141)."
436436
]
437437
},
438438
{

‎examples/04-Exporting-ranking-models.ipynb‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@
141141
"source": [
142142
"We use the synthetic train and test datasets generated by mimicking the real [Ali-CCP: Alibaba Click and Conversion Prediction](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1) dataset to build our recommender system ranking models. \n",
143143
"\n",
144-
"If you would like to use real Ali-CCP dataset instead, you can download the training and test datasets on [tianchi.aliyun.com](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1). You can then use [get_aliccp()](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/datasets/ecommerce/aliccp/dataset.py#L43) function to curate the raw csv files and save them as parquet files."
144+
"If you would like to use real Ali-CCP dataset instead, you can download the training and test datasets on [tianchi.aliyun.com](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1). You can then use [get_aliccp()](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/datasets/ecommerce/aliccp/dataset.py#L43) function to curate the raw csv files and save them as parquet files."
145145
]
146146
},
147147
{
@@ -459,7 +459,7 @@
459459
}
460460
},
461461
"source": [
462-
"In this example, we build, train, and export a Deep Learning Recommendation Model [(DLRM)](https://arxiv.org/abs/1906.00091) architecture. To learn more about how to train different deep learning models, how easily transition from one model to another and the seamless integration between data preparation and model training visit [03-Exploring-different-models.ipynb](https://github.com/NVIDIA-Merlin/models/blob/main/examples/03-Exploring-different-models.ipynb) notebook."
462+
"In this example, we build, train, and export a Deep Learning Recommendation Model [(DLRM)](https://arxiv.org/abs/1906.00091) architecture. To learn more about how to train different deep learning models, how easily transition from one model to another and the seamless integration between data preparation and model training visit [03-Exploring-different-models.ipynb](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/03-Exploring-different-models.ipynb) notebook."
463463
]
464464
},
465465
{
@@ -693,7 +693,7 @@
693693
"source": [
694694
"We trained and exported our ranking model and NVTabular workflow. In the next step, we will learn how to deploy our trained DLRM model into [Triton Inference Server](https://github.com/triton-inference-server/server) with [Merlin Systems](https://github.com/NVIDIA-Merlin/systems) library. NVIDIA Triton Inference Server (TIS) simplifies the deployment of AI models at scale in production. TIS provides a cloud and edge inferencing solution optimized for both CPUs and GPUs. It supports a number of different machine learning frameworks such as TensorFlow and PyTorch.\n",
695695
"\n",
696-
"For the next step, visit [Merlin Systems](https://github.com/NVIDIA-Merlin/systems) library and execute [Serving-Ranking-Models-With-Merlin-Systems](https://github.com/NVIDIA-Merlin/systems/blob/main/examples/Serving-Ranking-Models-With-Merlin-Systems.ipynb) notebook to deploy our saved DLRM and NVTabular workflow models as an ensemble to TIS and obtain prediction results for a qiven request. In doing so, you need to mount the saved DLRM and NVTabular workflow to the inference container following the instructions in the [README.md](https://github.com/NVIDIA-Merlin/systems/blob/main/examples/README.md)."
696+
"For the next step, visit [Merlin Systems](https://github.com/NVIDIA-Merlin/systems) library and execute [Serving-Ranking-Models-With-Merlin-Systems](https://github.com/NVIDIA-Merlin/systems/blob/stable/examples/Serving-Ranking-Models-With-Merlin-Systems.ipynb) notebook to deploy our saved DLRM and NVTabular workflow models as an ensemble to TIS and obtain prediction results for a qiven request. In doing so, you need to mount the saved DLRM and NVTabular workflow to the inference container following the instructions in the [README.md](https://github.com/NVIDIA-Merlin/systems/blob/stable/examples/README.md)."
697697
]
698698
}
699699
],

‎examples/05-Retrieval-Model.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -997,7 +997,7 @@
997997
"id": "155af447-97c4-4875-97ad-84e678fd7b40",
998998
"metadata": {},
999999
"source": [
1000-
"Note that above when we set `validation_data=valid` in the `model.fit()`, we compute evaluation metrics on validation set using the negative sampling strategy used for training. To determine the exact accuracy of our trained retrieval model, we need to compute the similarity score between a given query and all possible candidates. The higher the score of the positive candidate (the one that is already interacted with, i.e. target item_id returned by dataloader), the more accurate the model is. We can do this using the `topk_model` model that we create below via `to_top_k_encoder` method, and the following section shows how to instantiate it. The `to_top_k_encoder()` is a method of the [RetrievalModelV2](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/models/base.py) class. \n",
1000+
"Note that above when we set `validation_data=valid` in the `model.fit()`, we compute evaluation metrics on validation set using the negative sampling strategy used for training. To determine the exact accuracy of our trained retrieval model, we need to compute the similarity score between a given query and all possible candidates. The higher the score of the positive candidate (the one that is already interacted with, i.e. target item_id returned by dataloader), the more accurate the model is. We can do this using the `topk_model` model that we create below via `to_top_k_encoder` method, and the following section shows how to instantiate it. The `to_top_k_encoder()` is a method of the [RetrievalModelV2](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/models/base.py) class. \n",
10011001
"\n",
10021002
"`unique_rows_by_features` : A utility function allows extracting both unique user and item features tables as Merlin Dataset object that can easily be converted to a cuDF data frame. The function extracts unique rows from a specified dataset (transformed train set) based on a specified id-column tags (`ITEM` and `ITEM_ID`)."
10031003
]

0 commit comments

Comments
 (0)