Add introduction section to Transformations API page to document role of Transforms

[mkusnetsov]

Description

This PR adds an introduction section to the Transformations API page to:

• explain the principal purpose of transforms
• warn that most users don't need to play with these and that most attempts to do so don't do what users tend to think
• provide some guidance on when tweaking transforms may be appropriate and what other options user have when wanting to deal with transformed random variables

In addition this PR:

• removes a seemingly incorrect deprecation comment next to the ordered transform (I think it was accidentally left over from when univariate_ordered was deprecated)
• removes mention of SumsTo1, which is being deprecated
• organises instance and class names in the autosummary to
  1. alphebtize them, and
  2. add missing class names for the included instances

This PR assumes that the issue #5674 is closed (via PR #7207) to avoid extensive (and somewhat non-intuitive to casual user) guidance that will shortly be outdated

Related Issue

• [x] Closes #7040
• [x] Related to #6975, #5674, #7009

Checklist

• [x] Checked that the pre-commit linting/style checks pass
• [x] Included tests that prove the fix is effective or that the new feature works
• [x] Added necessary documentation (docstrings and/or example notebooks)
• [x] If you are a pro: each commit corresponds to a relevant logical change

Type of change

• [ ] New feature / enhancement
• [ ] Bug fix
• [x] Documentation
• [ ] Maintenance
• [ ] Other (please specify):

---

📚 Documentation preview 📚: https://pymc--7232.org.readthedocs.build/en/7232/

[welcome[bot]]

] :sparkling_heart: Thanks for opening this pull request! :sparkling_heart: The PyMC community really appreciates your time and effort to contribute to the project. Please make sure you have read our Contributing Guidelines and filled in our pull request template to the best of your ability.

[mkusnetsov]

Thanks, @ricardoV94! That's a good point - I pushed some changes to clarify transform kwarg as distinct from default_transform.

But I might be doing something wrong? Although I can see the commits and the changes, the preview documentation is still showing the original version, not the revised one... (I know it takes a while to re-build but it seems to be saying "Read the Docs build succeeded!")

[ricardoV94]

But I might be doing something wrong? Although I can see the commits and the changes, the preview documentation is still showing the original version, not the revised one... (I know it takes a while to re-build but it seems to be saying "Read the Docs build succeeded!")

It takes some time for the preview to update. I think it's correct now? https://pymcio--7232.org.readthedocs.build/projects/docs/en/7232/api/distributions/transforms.html

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 92.30%. Comparing base (4f6831e) to head (f29112f). Report is 2 commits behind head on main.

Additional details and impacted files

[](https://app.codecov.io/gh/pymc-devs/pymc/pull/7232?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=pymc-devs) ```diff @@ Coverage Diff @@ ## main #7232 +/- ## ======================================= Coverage 92.30% 92.30% ======================================= Files 100 100 Lines 16895 16895 ======================================= Hits 15595 15595 Misses 1300 1300 ``` | [Files](https://app.codecov.io/gh/pymc-devs/pymc/pull/7232?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=pymc-devs) | Coverage Δ | | |---|---|---| | [pymc/distributions/transforms.py](https://app.codecov.io/gh/pymc-devs/pymc/pull/7232?src=pr&el=tree&filepath=pymc%2Fdistributions%2Ftransforms.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=pymc-devs#diff-cHltYy9kaXN0cmlidXRpb25zL3RyYW5zZm9ybXMucHk=) | `98.47% <ø> (ø)` | |

[mkusnetsov]

Thank you for the kind words! It is correct now, yes. Will know that it takes a while, in the future. And yes - it absolutely makes sense to wait for the other PR.

I left some open questions on the underlying issue. Are any of them worth pursuing either in a separate issue or a discussion? Just checking because I assume once that issue is closed they might get lost.

[welcome[bot]]

] Congrats on merging your first pull request! :tada: We here at PyMC are proud of you! :sparkling_heart: Thank you so much for your contribution :gift:

[ricardoV94]

Thanks a ton @mkusnetsov, don't hesitate in opening issues/PRs for other areas you find documentation to be lacking