Add docs + slight refactor for num-complex and num-bigint dependencies

[mejrs]

• adds docs and examples for the num-complex and num-bigint dependencies
• also adds a paragraph to the features section of the guide, which was missing them
• adds nalgebra as a dev-dependency - this is required to test the num-complex example. I really wanted an example that shows using Complex in a linear algebra crate, which is probably what most people using the feature want to do. I don't like adding dependencies, but given that it requires two other crates I would feel uncomfortable not testing it.
• shuffles around some code:
  • I put the relevant feature-gated code in the same module as the docs
  • I put the code in scr/types/num that depends on the Py_LIMITED/PyPy cfg's in a single block
  • both these things reduce a lot of the cfg littering in that module
  • this does make the diffs a pain to review 😳 sorry!

Rendered

[davidhewitt]

Overall this is a really nice tidy-up, thank you!

My main query is regarding the #[must_use] annotations. I highlighted two but there's a few more. Are they really necessary?

[davidhewitt]

Agreed this is useful to have but I worry we'll forget to update the versions...

[mejrs]

I don't think there is a way to auto update it :/ This is definitely going to be an annoying maintenance burden going forward.

I've seen other crates document this like:

[dependencies]
# replace * with the current pyo3 version
pyo3 = { version = "*", features = ["num-bigint"] }

[davidhewitt]

👍 That seems like a really good idea. Could also say "check pyo3's Cargo.toml" for supported num-bigint version?

... or we could do something fun with an mdbook preprocessor to parse Cargo.toml and put the supported num-bigint version in the guide in a table 🙈

[mejrs]

or we could do something fun with an mdbook preprocessor to parse Cargo.toml and put the supported num-bigint version in the guide in a table 🙈

Can we do something dynamically in the docs? I'd really prefer something that can be straight up copy-pasted.

[davidhewitt]

I'm not aware of similar tricks to do dynamic docs, however if you want to go for something dynamic in the guide you might find the existing preprocessor I wrote useful: https://github.com/PyO3/pyo3/blob/main/guide/pyo3_version.py

[birkenfeld]

Since we have other locations where the current version must be substituted, I think the best way is a small (Python) script that replaces everything at once. This can then be run simply as part of the release process.

[mejrs]

I tried a couple of things but didn't find anything that didn't feel like a gross hack. So I've just taken the * approach as above.

[birkenfeld]

What's the "gross hack" with my suggestion?

[mejrs]

It's not, really. I figured out a proc macro that does it by just search+replacing text in a module, but it doesn't work in lib.rs and messes up the [src] links (which is pretty gross).

I don't like the idea of adding things to the release process for something that's at best "nice to have". It's not that big of a deal on its own but these things do add up.

[davidhewitt]

TBH I would be happy to have a python script to automate releasing (at the moment it's done manually by me), but i think that's best in a separate PR.

[mejrs]

I'm not sure how to fix the failing python3.9-x64 ubuntu-latest MSRV test. The problem is that nalgebra won't build on msrv (officially, they only support latest stable).

I see the following solutions:

• don't test the example 😢
• put nalgebra as an optional dependency (dev-dependencies can't be optional) and only turn it on when testing on latest stable. I'm not a fan of that showing up as a feature when it doesn't really do anything useful for users.

[davidhewitt]

Hmm, that's an awkward one.

I think I'd rather not do anything too complicated but agree it'd be nice to test the example. How about ditching nalgebra and writing example to find the complex roots of a quadratic polynomial instead? That's a reasonably simple formula which could be written without needing a third-party dependency.

[mejrs]

I've ignore'd the example to avoid the problem but I do want to keep it because it shows a good use case for using the feature.

I think that is all 👌

[kngwyu]

If you can afford it, could you please revise the tests to use with_gil?
BTW, thank you for all your efforts. Unfortunately, recently I don't have enough time for OSS, so I'm happy to see the project is supported this nice way.

[mejrs]

@kngwyu sure!

[davidhewitt]

Thanks!