move tree generation methods to src/sage/graphs/generators/trees.pyx

[dcoudert]

Fixes #39180 .

This PR implements the changes proposed in #39180 (comment):

• move src/sage/graphs/trees.pyx and src/sage/graphs/trees.pxd to src/sage/graphs/generators/.
• move to this file all methods for generating trees, including graphs.trees(), graphs.nauty_gentreeg(), graphs.BalancedTree(), graphs.FibonacciTree(), graphs.RandomTree(), graphs.RandomTreePowerlaw(), graphs.RandomLobster(), etc.
• add some documentation and examples showing the different ways to generate trees at the top of module trees.pyx.
• ensure that all internal links to moved methods are properly updated.

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation and checked the documentation preview.

⌛ Dependencies

[github-actions]

Documentation preview for this PR (built with commit 14c12f8; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[dcoudert]

I have opened issue #39864 for a random doctest error reported by CI that is not related to this PR: https://github.com/sagemath/sage/actions/runs/14265417106/job/39986034778?pr=39753#step:12:7936

Another random doctest not related to this PR (https://github.com/sagemath/sage/actions/runs/14265417106/job/39986033045?pr=39753#step:12:6259) is fixed in #39837.

[dcoudert]

@maxale, @DaveWitteMorris: some help reviewing this PR would be much appreciated

[DaveWitteMorris]

@dcoudert Thanks for making the PR. Sorry I have been busy and expect to still be busy for the rest of the month (and the PR has a lot of lines of code), so I don't think I will be able to do this soon. But I will look at it if it still needs review when I have time.

[dcoudert]

anyone to review this PR ?

[DaveWitteMorris]

I'm sorry, but I've been busy this summer. I have had very little time to spend on sagemath in the past two months, and there are several PRs I should review, but I don't know when I'll be able to get to them. I expect to get to this one eventually if nobody else does it in the meantime.

[dcoudert]

@fchapoton @tscrim could you help reviewing this PR.
The documentation preview looks good https://doc-pr-39753--sagemath.netlify.app/html/en/reference/graphs/sage/graphs/generators/trees.
Thanks.

[dcoudert]

do you see any other issues ?

[fchapoton]

ok

[dcoudert]

Thank you

[fchapoton]

ya un test super long dans les random k-trees qui mérite le tag "# long time", à faire ailleurs..

[dcoudert]

je note pour le test. C'est assez curieux car il y a des tests hypers longs sur le CI qui sont très rapides sur nos machines.