Big Rework of the Documentation #1432

LennartPurucker · 2025-06-20T11:36:33Z

Metadata

Reference Issue: N/A
New Tests Added: N/A
Documentation Updated: Yes
Change Log Entry: Reworked and streamlined all of the documentation.

Details

See changes.

LennartPurucker · 2025-06-20T11:36:45Z

@PGijsbers

codecov-commenter · 2025-06-20T11:46:11Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 52.69%. Comparing base (bc50a88) to head (33acd4f).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1432   +/-   ##
========================================
  Coverage    52.69%   52.69%           
========================================
  Files           36       36           
  Lines         4346     4346           
========================================
  Hits          2290     2290           
  Misses        2056     2056

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

PGijsbers · 2025-06-20T14:35:37Z

Please fix the regex in tests/test_openml/test_api_calls.py::test_authentication_endpoints_requiring_api_key_show_relevant_help_link

PGijsbers

I started reviewing but I wasn't entirely sure what to review.
Are there particular pointers, e.g., pages/tutorials that changed significantly? Things I really need to see before we merge? There are a number of things I noted that could be improved, e.g., using more common mkdocs-material features, such as admonitions and tabs. Those could also be iterated over in future PRs, which might be an easier way for me to give feedback as well (I could just set up a PR with my suggested improvements).

Other notes:

The favicon is interestingly only applied to subpages only. I am guessing this is some caching artifact on my end, though even an in-cognito browser seems to exhibit this behavior.

PGijsbers · 2025-06-20T14:44:47Z

docs/index.md

@@ -1,65 +1,79 @@
 # OpenML


We should just re-use the top-level README instead of introducing duplication, right? A docs/README.md is automatically shown on GitHub if there is no README.md in the root.

Mostly but not fully, here we can have more details.

Maybe generally, be aware that I mostly took the state that already existed, which did not have a lot of native mkdocs structure and some sub-optimal code choices. I mostly refactored the content.

here we can have more details

We can, but think it's fine not to in order to allow re-use and avoid desync.

PGijsbers · 2025-06-20T14:47:10Z

docs/index.md


 For more advanced installation information, please see the
-["Introduction"](../examples/20_basic/introduction_tutorial.py) example.
+["Introduction"](../examples/Basics/introduction_tutorial.py) example.


Suggested change

["Introduction"](../examples/Basics/introduction_tutorial.py) example.

["Introduction"](../examples/Basics/introduction_tutorial) example.

There are a number of warnings when serving the docs, including this broken link.

When I build locally, it also throws warnings for non-broken links, so I do not know how to judge which one is correct

I think this link is marked as broken, as it does not exist at the time the link checker comes in. The notebooks are only built later. It works locally

It does for you? I tried this one locally and it did not work for me.

Yes (with the committed fix from you)

PGijsbers · 2025-06-20T14:51:16Z

examples/introduction.py

@@ -0,0 +1,22 @@
+# %% [markdown]


Is there a reason this is a Python file instead of markdown?

It did not show up on the docs as .md.

Looking into it, it is because with markdown this file is not copied into the docs folder from the pre-existing script, I think. (scripts/gen_ref_pages.py)

examples/Basics/introduction_tutorial.py

LennartPurucker · 2025-06-20T15:13:38Z

I guess you can review all the changes and documentation as much as you like as it is generally very outdaed and I mostly moved it or deleted stuff

Co-authored-by: Pieter Gijsbers <p.gijsbers@tue.nl>

LennartPurucker · 2025-06-20T15:37:12Z

Fun fact: the regrex test crashing only happened because of PyCharms refactor logic also changing one but not the other value. Without it, I would not have even known that the link to the documentation in the code is totally wrong already.

SubhadityaMukherjee · 2025-07-04T12:10:19Z

Alright, I fixed some minor things and the rest looks good. I still need some more clarification on these : @LennartPurucker

In Advanced/create_upload_tutorial.py, the title is “Dataset is a numpy array” instead of Creating and uploading datasets. I am unable to figure out how to change this :/

/Advanced/tasks_tutorial/ : resampling link leads to an empty search

Details : this doesnt seem like a good title :/ details of what exactly? - the page has information about config and docker and stuff

Openml.org/cite doesnt exist in contributing

LennartPurucker · 2025-07-04T12:31:05Z

You need to remove this: https://github.com/openml/openml-python/blob/maint/rework_docu/examples/Advanced/create_upload_tutorial.py#L27 and likely other level one headings and ===. All headings must be level two, I think, so at most ##.
I have no idea where the new WebUI shows the potential estimation procedures. I am always using the REST API to figure this out. Maybe someone else knows a new link for this?
I think the title of the page is already Advanced User Guide, no? And the nav button is just a summary / prompt to click on this for more in-depth notes. I would not go over a one-word value for this. But I also don't have any better ones in my mind right now.
Funny, I think it did during the Hackathon (?) I guess it is now: https://www.openml.org/terms

SubhadityaMukherjee · 2025-07-04T12:33:35Z

Okay cool, Ill do that

SubhadityaMukherjee · 2025-07-07T15:11:25Z

Okay its good to go from my side

LennartPurucker · 2025-07-07T15:12:44Z

Did you update the citation link?

SubhadityaMukherjee · 2025-07-07T15:20:02Z

Yep!

LennartPurucker · 2025-07-07T15:21:02Z

Supi, LGTM from me, feel free to merge!
(we need to check if it gets deployed correctly)

SubhadityaMukherjee

Approving this, but it remains to be seen if the building works now. Can't really test it any other way

LennartPurucker added 7 commits June 19, 2025 19:55

maint: update docu

b6986e6

finalize text on docu page

6cc374a

add: refactor basic tutorials

5197ddc

finalize basic examples

2a74c9a

refactor advanaced examples

b3fbfa2

fix nav and website

5b0f33d

update PR template

baadaf6

PGijsbers reviewed Jun 20, 2025

View reviewed changes

LennartPurucker and others added 3 commits June 20, 2025 17:16

Update docs/index.md

993c6af

Co-authored-by: Pieter Gijsbers <p.gijsbers@tue.nl>

Update examples/Basics/introduction_tutorial.py

c517a80

Co-authored-by: Pieter Gijsbers <p.gijsbers@tue.nl>

refactor docu link

d56ece4

SubhadityaMukherjee and others added 3 commits June 30, 2025 12:11

Merge branch 'develop' into maint/rework_docu

302bbc4

minor changes

0b670a3

minor changes

fff8a43

minor changes

33acd4f

SubhadityaMukherjee approved these changes Jul 9, 2025

View reviewed changes

SubhadityaMukherjee merged commit eed10f7 into develop Jul 9, 2025
13 checks passed

SubhadityaMukherjee deleted the maint/rework_docu branch July 9, 2025 10:55

PGijsbers mentioned this pull request Nov 16, 2025

Convert documentation to mkdocs #1339

Closed

	["Introduction"](../examples/Basics/introduction_tutorial.py) example.
	["Introduction"](../examples/Basics/introduction_tutorial) example.

Uh oh!

Big Rework of the Documentation #1432

Big Rework of the Documentation #1432

Uh oh!

Conversation

LennartPurucker commented Jun 20, 2025

Metadata

Details

Uh oh!

LennartPurucker commented Jun 20, 2025

Uh oh!

codecov-commenter commented Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

PGijsbers commented Jun 20, 2025

Uh oh!

PGijsbers left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LennartPurucker Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LennartPurucker commented Jun 20, 2025

Uh oh!

LennartPurucker commented Jun 20, 2025

Uh oh!

SubhadityaMukherjee commented Jul 4, 2025

Uh oh!

LennartPurucker commented Jul 4, 2025

Uh oh!

SubhadityaMukherjee commented Jul 4, 2025

Uh oh!

SubhadityaMukherjee commented Jul 7, 2025

Uh oh!

LennartPurucker commented Jul 7, 2025

Uh oh!

SubhadityaMukherjee commented Jul 7, 2025

Uh oh!

LennartPurucker commented Jul 7, 2025

Uh oh!

SubhadityaMukherjee left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

codecov-commenter commented Jun 20, 2025 •

edited

Loading

PGijsbers left a comment •

edited

Loading

LennartPurucker Jun 20, 2025 •

edited

Loading