Add missing docstring examples

[braaannigan]

Description

Some of the methods lack any API examples. The attached CSV shows a list of function urls that do not currently have examples: has_examples.csv

This is a really good first issue. Some of these methods - such as the I/O methods - are more advanced but there are plenty of simpler expression and series methods there are good for new contributors. If anyone wants to have a go please reply to this issue saying which group of methods you are working on. It is best to do small PRs with just a few methods at a time.

If anyone is having trouble with the contribution process @ me here (or on discord which I see more easily)

Link

No response

[stinodego]

Please refer to our contributing guide for guidance on writing good doc examples:
https://pola-rs.github.io/polars/development/contributing/test/#writing-doc-examples

[braaannigan]

@stinodego Was thinking I should break the missing examples into more manageable chunks with an issue each, what do you think?

[stinodego]

I don't think that's necessary. If people want to contribute docstring examples, this issue is sufficient to find out where the gaps are.

[deanm0000]

Should the file be called needs_examples instead of has_examples? I noticed there's a lot of Series methods on there that probably have Expr methods. Is there an automated way to put a link on the Series method to the Expr method for near examples? Also the list has a lot of deprecated methods that shouldn't have examples. The pages that are deprecated have a div class="deprecated" to make automated filtering easier.

[r-brink]

This looks like a fun one to familiarise myself again with the contribution process. I'll have a look at the csv file and update here if when I started working on a batch

[r-brink]

I have created an initial PR for the following items on the list

https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.abs.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.cbrt.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.exp.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.log.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.log10.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.log1p.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.skew.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.sqrt.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.is_sorted.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.null_count.html

[jcrozum]

I would like to work on this, starting with the datetime functions.

Examples are not desired for deprecated functions, correct? I will skip these to start, but can always add them later.

Also, it looks like many of these functions now have examples. I can update the list.

[MarcoGorelli]

great to see the community effort!

I'd suggest skipping anything deprecated

[jcrozum]

I created a PR for these:
https://pola-rs.github.io/polars/py-polars/html/reference/expressions/api/polars.Expr.dt.date.html
https://pola-rs.github.io/polars/py-polars/html/reference/expressions/api/polars.Expr.dt.datetime.html
https://pola-rs.github.io/polars/py-polars/html/reference/expressions/api/polars.Expr.dt.millisecond.html
https://pola-rs.github.io/polars/py-polars/html/reference/expressions/api/polars.Expr.dt.nanosecond.html
https://pola-rs.github.io/polars/py-polars/html/reference/expressions/api/polars.Expr.dt.time.html

The other functions listed for datetime are deprecated.

[jcrozum]

I updated the list of missing examples below.
removed_from_needed_examples_list.csv
updated_missing_examples_list.csv

[tim-stephenson]

Another update to the list
removed_from_needed_examples_list.csv
updated_missing_examples_list.csv

[MarcNuebel]

I created a PR for
https://pola-rs.github.io/polars/py-polars/html/reference/api/polars.read_csv.html

[jmgonzalezro]

How can I contribute? Just downloading the csv, checking what the fucntions pending do, and creating docstrings into the functions? First timmer here.

[r-brink]

I just opened a PR to add more examples to the docs. See below for the ones I added.

• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.name.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.shape.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.implode.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.nan_max.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.nan_min.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.product.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.list.contains.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.list.first.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.list.last.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.list.max.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.list.mean.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.list.min.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.list.reverse.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.list.sum.html
• https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.list.unique.html

Here the updated overview. I also removed read_csv

updated_missing_examples_list_09012024.csv

NOTE: some of the examples above where already added and merged, but not mentioned here.

[r-brink]

How can I contribute? Just downloading the csv, checking what the fucntions pending do, and creating docstrings into the functions? First timmer here.

@jmgonzalezro Have a look at the remaining docstrings that are missing an example. I just shared an updated overview. Pick the ones you want to work on and have fun. The contribution guide can help you set up your environment and create a PR: https://docs.pola.rs/development/contributing/

[mbuhidar]

Created a PR to improve formatting for Series.binary.encode and Series.binary.decode examples. Also added an example case for Series.binary.decode with the strict parameter set to False.

[tharunsuresh-code]

Hey, can I take this up?

I would like to add doc examples to the following:

https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.explode.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.limit.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.new_from_index.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.rechunk.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.shrink_dtype.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.reinterpret.html
https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.get_chunks.html

I am confused for the below function, how to write a short and good example, any help here is much appreciated.

https://pola-rs.github.io/polars/py-polars/html/reference/series/api/polars.Series.shrink_to_fit.html

Removed entries which already has doc examples, and the above changes.
updated_missing_examples_list_05112024.csv

[montanarograziano]

Hey, I've created a PR for:
https://pola-rs.github.io/polars/py-polars/html/reference/dataframe/api/polars.DataFrame.limit.html
Here's the updated list without it:
missing_docstrings_updated.csv

[montanarograziano]

Added a few more examples in this PR.

I removed these from the csv and also cleaned entries already resolved.
Here' the updated version:
missing_docstrings_updated.csv
I've noticed that for all the entries regarding types, (example: https://pola-rs.github.io/polars/py-polars/html/reference/api/polars.Float64.html) the link is broken: does it refer to https://docs.pola.rs/py-polars/html/reference/api/polars.datatypes.Int64.html?
If so, which kind of examples are expected? Thank you!

[stinodego]

I'm going to close this one as we're pretty much fully covered at this point.

There are a few entries left over where it's not exactly clear how to best give examples, e.g. DataType classes or I/O functionality. We can look at those separately.

Thanks to everyone who has contributed!