Skip to content

Revamp the documentation - #745

Open
hieuddo wants to merge 6 commits into
PreferredAI:masterfrom
hieuddo:feat/contributing-standards
Open

hieuddo wants to merge 6 commits into
PreferredAI:masterfrom
hieuddo:feat/contributing-standards

Conversation

@hieuddo

@hieuddo hieuddo commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Description

Follows #744. The docs had fallen behind the code, so this PR fixes what's broken, adds what's missing, and replaces "For Developers" and "For Researchers" with one User Guide. Each part is its own commit, so it can be reviewed one at a time:

  1. Fix broken examples, links and setup steps. The examples in "Using your Own Data", "My First Prediction" and FoodRecce run again. The 20 dataset links in cornac/datasets/README.md and two README links work again. The install and contributor pages now say Python 3.10+, master, and the current setup commands.
  2. Complete the API reference and examples list. This adds entries for ANN, BERT4Rec, FPMC, GPTop, SANSA, SASRec, TIGER, TransformerRec and VEBPR, seven dataset loaders, NextBasketEvaluation, the metric base classes and PSTResult. FM and Baseline Only now render, and four examples are added to examples/README.md.
  3. Contributors Guide. Everything about contributing is now in one place: the fork-and-PR page (with Getting Started folded in), plus CONTRIBUTING.md and the add-model/add-metric tutorials, shown on the site through MyST includes so there is one copy of each. The contributor material from "For Researchers" moves into the add-model tutorial. The tutorial now asks for an example script, as CONTRIBUTING.md already does.
  4. One User Guide: Installation, Quickstart, Loading Data, Models and Tasks, Evaluation and Tuning, Making Recommendations, Saving and Serving, FoodRecce Example. Text from the old pages moves with its wording (git diff --color-moved shows it as moved), and duplicates are gone; for example, tuning was explained on both persona pages. "Models and Tasks" is new: it covers next-item, next-basket, semantic IDs and bundle recommendation, each with its data format, evaluation method, models and an example.

Every code example on the user pages was run with Cornac 3.2.0, and the outputs shown come from those runs. The only exceptions are the TIGER training run and the sentence-transformers encoding, which are compiled but not run. The serving page was tested end to end with Flask and gunicorn. The docs build with fewer warnings than before, and none come from the guide pages.

The old "I am a developer", "I am a researcher" and Getting Started pages are removed without redirects. Links to them in this repo now point to the new pages, and the old pages stay readable in the v3.2.0 docs. One link outside this repo, in the cornac-ab README, points to the old serving section; I can update it once this is merged.

A new docs workflow runs docs/check_listings.py on each pull request and fails if a model, dataset loader or example is missing from the API reference or the READMEs.

Related Issues

Closes #744. Also covers #646.

Checklist:

  • I have added tests. (docs only)
  • I have updated the documentation accordingly.
  • I have updated README.md (if you are adding a new model).
  • I have updated examples/README.md (if you are adding a new example).
  • I have updated datasets/README.md (if you are adding a new dataset).

@qtuantruong

Copy link
Copy Markdown
Member

would a CI check that fails when a new model, dataset loader or example isn't listed be useful? I can add it in a follow-up.

yes, pls add that check

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] Docs out of date: failing examples, dead links and missing API entries

2 participants