add method orient to Graph

[dcoudert]

As suggested by @maxale in #38758 (comment), we add a method to apply an orientation function to a graph and obtain the corresponding directed graph.

📝 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 bb3749d; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[tscrim]

Lines 172 to 175 are never reached since they are an "else" after two cases, one of which must be true. Is line 172 supposed to be an if?

[dcoudert]

These lines can be reached setting data_structure=None, immutable=None and sparse=True or False.

In fact, lines 154-182 are copy-paste from method copy in generic_graph.py. May be I should make a method like _choose_data_structure_for_copy in generic_graph.py and use it for both methods ?

[tscrim]

Ah, I see. It’s fine for now. Then can you add doctests covering those cases?

[dcoudert]

We'll see if the new tests are sufficient.

[tscrim]

That should be good. Thank you.

[dcoudert]

Thanks for the review.