8000 Add links to examples from the docstrings and user guide · Issue #30621 · scikit-learn/scikit-learn · GitHub
[go: up one dir, main page]
Skip to content

Add links to examples from the docstrings and user guide #30621

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.

Sign up for GitHub

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

Jump to bottom
Open
StefanieSenger opened this issue Jan 10, 2025 · 137 comments · May be fixed by #31476
Open

Add links to examples from the docstrings and user guide #30621

StefanieSenger opened this issue Jan 10, 2025 · 137 comments · May be fixed by #31476
Labels
Documentation good first issue Easy with clear instructions to resolve Meta-issue General issue associated to an identified list of tasks Sprint

Comments

@StefanieSenger
Copy link
Contributor
StefanieSenger commented Jan 10, 2025 •
edited
Loading

TLDR: Meta-issue for new contributors to add links to the examples in helpful places of the rest of the docs.

Description

This meta-issue is a good place to start with your first contributions to scikit-learn.

This issue builds on top of #26927 and is introduced for easier maintainability. The goal is exactly the same as in the old issue.

Here, we improve the documentation by making the Examples more discoverable by adding links to examples in relevant sections of the documentation in the API documentation and in the User Guide:

  • the API documentation is made from the docstrings of public classes and functions which can be found in the sklearn folder of the project
  • the User Guide can be found in the doc/modules folder of the project

Together with the examples (which are in the examples folder of the project), these files get rendered into html when the documentation is build and then are displayed on the scikit-learn website.

Important: We estimate that only 70% of the examples in this list will ultimately be referenced. This means part of the task is deciding which examples deserve being referenced and we are aware that this is not a trivial decision, especially for new contributors. We encourage you to share your reasoning, and a team member will make the final call. We hope this isn’t too frustrating, but please know that evaluating an example is not just an exercise for new contributors; it’s a meaningful and valuable contribution to the project, even (and especially) if the example you worked on doesn’t end up being linked.

Workflow

We recommend this workflow for you:

  1. have pre-commit installed in your environment as in point 10 of How to contribute in the development guide (this will re-format your contribution to the standards used in scikit-learn and will spare you a lot of confusion when you are a beginner)

  2. pick an example to work on

    • Make sure your example of interest had not recently been claimed by someone else by looking through the discussion of this issue (you will have to load hidden items in this discussion). Hint: If somebody has claimed an example several weeks ago and then never started it, you can take it. You can also take over tasks marked as stalled.
    • search the repo for other links to your example and check if the example is already linked in relevant parts of the docs
      • how to search the repo: a) find the file name of your example in the examples folder (it starts with plot_...); b) use full text search of your IDE to look for where that name appears
      • you can totally ignore the "Gallery examples" on the website, as it is auto-generated; do only look for real links in the repo
    • comment on the issue to claim an example (you don't need to wait for a team member's approval before starting to work)

  3. find suitable spots in either the API documentation or the User Guide (or both) where users would be happy to find your example linked

    • read through your example and understand where it is making its most useful statements
    • how to find a good spot (careful: we are extremely picky here)
      • if the example demonstrates a certain real world use case: find where in the User Guide the same use case is treated or could be treated
      • if the example shows how to use a certain param: the param description in the API documentation might be a good spot to put the link
      • if the example compares different techniques: this highly calls for mentioning it in the more theoretical parts of the User Guide
      • not all the examples listed here need to be referenced: a link to an example on simply how to use some estimator, doesn't add enough value
        • if you find an example that doesn't add enough value to be linked: please leave a comment here; this kind of contribution is highly appreciated
    • not a good spot: the See Also section, which is (theoretically) reserved for links to other API functionalities, not examples

  4. add links

    • An example with the path examples/developing_estimators/sklearn_is_fitted.py whould be referenced like this:
      :ref:`sphx_glr_auto_examples_developing_estimators_sklearn_is_fitted.py`
    • see this example PR, that shows how to add a link to the User Guide: DOC add link to sklearn_is_fitted example in check_is_fitted #26926
    • we aim not to use the .. rubric:: Examples section to put the example if possible, but to integrate it into the text; be aware that if you add a link like this :ref:`title <link>`, you can change its title so that the example's title gets substituted by your picked title and the link can be fitted more nicely to the sentences
    • please avoid adding your link to a list of other examples, since we strive to add the links in the most relevant places
    • please avoid adding a new .. rubric:: Examples section

  5. test build the documentation before opening your PR

  6. open PR

    • use a PR title like DOC add links to <name of example> (starting with DOC)
    • do not refer to this issue on the title of the PR, instead:
    • do refer to this issue using in the Reference Issues/PRs section of your PR, do refer to this issue using "Towards #30621" (do not use "Closes #..." or "Fixes #...")

  7. check the CI

    • After the CI tests have finished (~90 minutes) you can find one that says "Check the rendered docs here!". In there, you can look into how the CI has built the documentation for the changed files to check if everything looks alright. You will see something like auto_examples/path_to_example, [dev], [stable], where the first link is your branche's version, the second is the main dev branch and the third link is the last released scikit-learn version that is used for the stable documentation on the website.
    • if the CI shows any failure, you should to take action by investigating and proposing solutions; as a rule of thump, you can find the most useful information from the CIs, if you click the upper links first; in any case you need to click through several layers until you see actual test results with more information (and until it looks similar to running pytest, ruff or doctest locally)
    • if the CI shows linting issues, check if you have installed and activated pre-commit properly, and fix the issue by the action the CI proposes (for instance adding or deleting an empty line)
    • if you are lost and don't know what to do with a CI failure, look through other PRs from this issue; most things have already happened to others
    • sometimes, http request errors such as 404 or 405 show up in the CI, in which case you should push an empty commit (git commit --allow 8000 -empty -m "empty commit to re-trigger CI")

  8. wait for reviews and be ready to adjust your contribution later on

Expectation management for new contributors

How long will your first PR take you up until the point you open a PR?

  • 8-16 hours if you have never contributed to any project and have only basic or no understanding of the workflow yet
  • 2-8 hours if you know the workflow and are just new to scikit-learn (more to the shorter end if you know about linting and sphinx and are able to address CI outputs)
  • 1-2 hours for your 2nd, 3rd, ... PR on the same issue for everyone

How long will it take us to merge your PR?

  • we strive for a scikit-learn member to look at your PR within a few days and suggest changes depending on technical quality of the PR and an assessment of added value to the user (if the link is useful to have in the spot you suggested)
  • we strive for a maintainer to evaluate your PR within a few weeks; they might also suggest changes before approving and merging
  • the whole process on average takes several weeks and can take up months, depending of availability of maintainers and on how many review cycles are necessary

ToDo

Here's a list of all the remaining examples:

What comes next?
@StefanieSenger StefanieSenger added Documentation Sprint good first issue Easy with clear instructions to resolve Meta-issue General issue associated to an identified list of tasks labels Jan 10, 2025
@StefanieSenger StefanieSenger mentioned this issue Jan 10, 2025
Closed
@marenwestermann
Copy link
Member

Leaving a comment so I get updates about incoming PRs :)

@virchan
Copy link
Member
virchan commented Jan 10, 2025

Commenting to stay updated!

@sarang-26
Copy link
sarang-26 commented Jan 11, 2025 •
edited
Loading

Hi Sklearn Team,

excited to work on this on this issue. I will be following the workflow and start working on this.

Its my first time contributing to sklearn, hence hoping I learn as much as possible and also contribute to the open source community!

I will be working on

examples/classification:
plot_classifier_comparison.py
plot_digits_classification.py

Updated:

Hi @StefanieSenger, I have found few places, where I can place examples from SVM in the User Guide.
Could I also select few more examples to work on:
plot_custom_kernel.py
plot_iris_svc.py
plot_linearsvc_support_vectors.py
plot_oneclass.py
plot_rbf_parameters.py

Is it okay, to select a group of this size and work on this in a single PR? (from review perspective)

@AlviseSembenico
Copy link

Hey team!
I will also work on this in the coming days as my first contribution!

@StefanieSenger
Copy link
Contributor Author
8000

Hi @sarang-26, nice to hear you want to contribute.
plot_classifier_comparison.py was recently claimed by someone else.
You can still work on plot_digits_classification.py, I think.

@stefanogaspari
Copy link
Contributor

Working on examples/covariance/plot_mahalanobis_distances.py

@Crucible0
Copy link

Hi, I'd like to work on adding references for plot_iris_dtc.py and plot_tree_regression_multioutput.py. Could you confirm if they're available for contribution? Thank you!

@StefanieSenger
Copy link
Contributor Author
StefanieSenger commented Jan 11, 2025 •
edited
Loading

Hi, I'd like to work on adding references for plot_iris_dtc.py and plot_tree_regression_multioutput.py. Could you confirm if they're available for contribution? Thank you!

Awesome! Happy to see your contribution.
It looks like nobody has worked on it yet, I cannot confirm though. 🤷 You need to check yourself (see workflow 1. b), it's part of the process of submitting a PR.

@Rchintalapati0111
Copy link

Hi @StefanieSenger!
I am a first-time contributor to Scikit-learn and would like to contribute to the example plot_confusion_matrix.py from the applications category. Please let me know if it is available and if there are any additional guidelines I should follow.
Thank you

@Peeyush2
Copy link

Hello @StefanieSenger

I am looking for open-source contributions. This will be my first contribution, I would like to work on file
examples/feature_selection:
plot_feature_selection.py

Thank you!

@Vish75
Copy link
Vish75 commented Jan 11, 2025

Hello @StefanieSenger

I am quite new to open-source contributions. I would like to work on examples/model_selection/plot_cv_predict.py.

Thank you

@hriti99
Copy link
hriti99 commented Jan 13, 2025

Hello @StefanieSenger
I am looking for open-source contributions, this will be my first contribution.
I will work on the file : plot_image_denoising.py

Thank you!

@StefanieSenger
Copy link
Contributor Author

Hi @StefanieSenger, I have found few places, where I can place examples from SVM in the User Guide.
Could I also select few more examples to work on:
plot_custom_kernel.py
plot_iris_svc.py
plot_linearsvc_support_vectors.py
plot_oneclass.py
plot_rbf_parameters.py

Is it okay, to select a group of this size and work on this in a single PR? (from review perspective)

Hi @sarang-26, I'd say that's too many. Please split it up or go one by one.

@Crucible0 Crucible0 mentioned this issue Jan 15, 2025
Closed
@Si-ddhartha
Copy link

Hello @StefanieSenger

I am quite new to open-source contributions. I would like to work on examples/model_selection/plot_underfitting_overfitting.py

Thank you!

@Crucible0
Copy link
Crucible0 commented Jan 15, 2025 •
edited
Loading

Hi! I have created a pull request: #30650 . It adds a reference to the plot_iris_dtc example in the DecisionTreeClassifier documentation. Please let me know if any further changes are needed!

@simarssidhu
Copy link
Contributor

Hi @StefanieSenger,

I'm new to open source contributions, I was wondering if I could work on:

  • plot_weighted_samples.py in examples/svm

Thank you,
Simar

@anotherk1nd
Copy link

Hello! I'd like to claim this example as my first contribution:

scikit-learn/examples/mixture/plot_concentration_prior.py

Thanks!
Josh

@sotagg
Copy link
Contributor
sotagg commented Jan 17, 2025

Hello @StefanieSenger,

This will be my first contribution to scikit-learn.
I'd like to work on examples/linear_model/plot_ols.py if it's available.

Thank you!

@sotagg
Copy link
Contributor
sotagg commented Jan 19, 2025

Hello @StefanieSenger,
I just realized that plot_ols.py is already referenced in the User Guide, so there isn’t much to add there.
My apologies for the oversight.

I would still love to contribute, so I’d like to switch to plot_ols_ridge_variance.py if it’s still available.
Please let me know if that works.

Thanks for your patience.

@StefanieSenger
Copy link
Contributor Author
StefanieSenger commented Jan 19, 2025 •
edited
Loading

I just realized that plot_ols.py is already referenced in the User Guide, so there isn’t much to add there.

That's an excellent finding, thank you, @sotagg!
Finding that we don't need to reference one of the examples is part of the workflow, so that's been just right. I will check it off the list.

plot_ols_ridge_variance.py looks fine, but I didn't check in depth (that's on you again).

@simarssidhu simarssidhu mentioned this issue Jan 20, 2025
Closed
@PriyankaWani66
Copy link

Hi @StefanieSenger ,

I'd like to contribute to this issue by adding references to the following examples in the documentation:
examples/neighbors/plot_lof_novelty_detection.py
examples/neighbors/plot_lof_outlier_detection.py

I have checked the comments and PRs and didn't find any related work for these files. Please confirm if I can proceed with these contributions.

Thanks!

@sotagg sotagg mentioned this issue Jan 20, 2025
Merged
@sidg1215
Copy link

Hi @StefanieSenger,
I'd like to contribute by adding references to examples/linear_model/plot_logistic.py. I have checked for the comments and PRs and I don't see anything related. Please let me know if I can start working on this.

Thank you,
Sid

@chibihime
Copy link
chibihime commented May 26, 2025 •
edited
Loading

Hi @chibihime, nice. I would recommend to select a single link and then claim it, so others know it's taken.

Thanks! @StefanieSenger I'd like to claim plot_semi_supervised_versus_svm_iris.py to work on adding links to relevant sections of the API documentation and User Guide.

@tjnorred
Copy link
Contributor

Hi,

I would like to work on plot_prediction_latency.py for my first contribution.

Thank you.

@devasadhu
Copy link

Hi @StefanieSenger,

I’m excited to start contributing to scikit-learn and would love to work on some example scripts to add missing documentation links or improvements.

Could I please be assigned any of the following examples? This will be my first contribution, and I’m eager to learn:

plot_sparse_logistic_regression_mnist.py

plot_anomaly_comparison.py

plot_metadata_routing.py

plot_roc_curve_visualization_api.py

plot_train_error_vs_test_error.py

plot_linearsvc_support_vectors.py

Also, would it be okay to work on multiple examples in a single PR, or do you recommend submitting smaller individual PRs for better review?

Thank you very much for your guidance!

@StefanieSenger
Copy link
Contributor Author
StefanieSenger commented May 27, 2025 •
edited
Loading

Hi @devasadhu, happy about your eagerness. Best is, to select a single link and then claim it, so others know it's taken. And then please work on one example at a time. You can go through several examples one by one.

@Namit24
Copy link
Namit24 commented May 28, 2025

@StefanieSenger Hey is this issue still open? One of my initial contributions so I feel this would be great

@Ganasekhar-gif
Copy link

Hi @StefanieSenger

I'd like to work on adding a reference to plot_monotonic_constraints.py in the HistGradientBoostingRegressor API docstring. Let me know if this sounds good!

@devasadhu
Copy link

Hi @StefanieSenger,
I'd like to work on adding documentation links for the plot_train_error_vs_test_error.py example.
This will be my first contribution.
Thank you!

@Ganasekhar-gif Ganasekhar-gif mentioned this issue May 28, 2025
Closed
@supersom
Copy link

Hi @StefanieSenger ,
Would it help to link the example plot_huber_vs_ridge.py in the user guide for ridge regression demonstrating regressors that are robust to outliers? If so, I can add it. Thanks!

AStefankiv added a commit to AStefankiv/scikit-learn that referenced this issue May 29, 2025
@AStefankiv
Add links to examples from the docstrings and user guide scikit-learn…
e042fdc 
…#30621
@lsakovykh
Copy link

Hi @StefanieSenger!

I want to make my first contribution to scikit-learn!

I chose the plot_ridge_coeffs.py example to work with. From my searches, this example doesn't seem to have any external references in the main documentation (API or User Guide) yet.

@Ganasekhar-gif
Copy link

Hi @StefanieSenger,

I haven't see anyone claimed plot_ensemble_oob.py. so can i take it.

Thank you!

@lsakovykh lsakovykh mentioned this issue May 29, 2025
Open
@Ganasekhar-gif Ganasekhar-gif mentioned this issue May 30, 2025
Open
@virchan virchan mentioned this issue May 31, 2025
Open
@KSruthiVel
Copy link

Hi @StefanieSenger, I would like to work on examples/cluster/plot_digits_linkage.py for my first contribution. I have checked and did not find any references or pull requests

@shivamchhuneja
Copy link
Contributor

Hi! I'd like to claim plot_monotonic_constraints.py - starting work on this 🚀

@shivamchhuneja shivamchhuneja mentioned this issue Jun 2, 2025
Merged
@VirenPassi
Copy link

Hello @StefanieSenger,

I’m excited to make my first contribution to scikit-learn! I'd like to work on adding a documentation link for the example plot_rfe_with_cross_validation.py in the feature selection section.

Thank you! 🙌

@Marcilesm Marcilesm mentioned this issue Jun 2, 2025
Open
@shivamchhuneja
Copy link
Contributor

Hi @StefanieSenger forgot to tag you earlier, not sure if it still got picked or not.

Added an example to monotonic constraints in ensemble and opened this: #31471

@VirenPassi VirenPassi linked a pull request Jun 3, 2025 that will close this issue
Open
@tjnorred tjnorred mentioned this issue Jun 4, 2025
Merged
@mithunkar mithunkar mentioned this issue Jun 4, 2025
Open
@Narendersingh007
Copy link
Narendersingh007 commented Jun 5, 2025 •
edited
Loading

I’d like to work on linking the example: plot_ard.py As a part of my first contribution on github

@natmokval
Copy link
Contributor

Hi @StefanieSenger, I would like to work on ' plot_mahalanobis_distances.py'.

@shivamchhuneja
Copy link
Contributor
shivamchhuneja commented Jun 5, 2025 •
edited
Loading

I’d like to work on linking the example: plot_example_xyz.py. As a part of my first contribution on github

hey @Narendersingh007, you might want to check out the list above and see if the ones that are unchecked are unclaimed and claim one

@natmokval natmokval mentioned this issue Jun 5, 2025
Open
@Narendersingh007
Copy link

hi @StefanieSenger I would like to work on ' plot_ard.py'

@laharigandrapu11
Copy link

Hi @StefanieSenger, I'd like to work on "plot_varimax_fa.py" as my first contribution to scikit-learn.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation good first issue Easy with clear instructions to resolve Meta-issue General issue associated to an identified list of tasks Sprint
Projects
None yet
Milestone
No milestone
0