Docstrings API examples

[anopsy]

Description

Added examples to:

• sklego/preprocessing/formulaictransformer.py
• sklego/preprocessing/identitytransformer.py
• sklego/preprocessing/pandastransformers.py
• sklego/preprocessing/projections.py
• sklego/preprocessing/repeatingbasis.py

[FBruzzesi]

The difference between the two keywords Example and Examples is subtle but:

• Examples is a keyword in mkdocstring griffe and has the example as a section, always displayed
• Example is a keyword in mkdocs material and adopts the boxed colored layout.

I would opt for the first one as it is numpydoc compliant. However I can see why the second option is also nice and appealing.
If we go for that, maybe I would suggest to use the a collapsible blocks

??? example
...

so that it is closed by default and lowers the clutter in the page, yet easy to access for a user.

@koaning thoughts?

[FBruzzesi]

How did that survive lint CI/CD in the first place? 🙈

[anopsy]

Ach so! Thank you for explaining, I also fell for this little test tube in the corner. Just to make sure, the "example" also allows for collapsing, isn't?
Waiting for your decision and will adjust it accordingly

[FBruzzesi]

Yes, for "example" it is just a matter of default (expanded vs collapsed).
Let's wait for Vincent feedback/preference to weight on this 🙃

[koaning]

Maybe go for usage instead?

[FBruzzesi]

I thought Usage keyword was google-style specific, but at least from the griffe docs it seems it is neither google or numpy.

At the end of the day I believe the only difference is that keywords get bold-ed (example in screenshot).

I think for now the safest way to proceed is to use Examples keyword as it would have the lowest impact and require less changes.

[anopsy]

Okay, I'll do Examples then, if you change your mind, just ping me

[anopsy]

I didn't add preprocessing.intervalencoder.IntervalEncoder because I need to delve more into what is it exactly doing. According to the docs strings it's "bending" / "smoothing" the values in X . I checked what "smoothing" in math is doing, and I have my doubts if you meant IntervalEncoder to do smoothing or you meant a monotonic transformation. If you could give me a hint what to research, I'd be really grateful

[FBruzzesi]

Thanks for fixing that everywhere 👌✨

[FBruzzesi]

@anopsy I hope that the Interval Encoders user guide and the examples there help.

If it doesn't, feel free to reach out to me on socials as well, since user guide would also need some improvements.

Disclaimer: I personally never used the feature