support doc_mode attribute to limit docs to a single language

[davidhewitt]

This is a prototype attempt at #5269

It actually works, which is pretty promising!

#[pyo3::pymodule]
/// A simple example of a native module with varying docs.
///
#[pyo3_doc_mode(doc_mode = "rust")]
/// This is a Rust-only comment.
#[pyo3_doc_mode(doc_mode = "python")]
/// This is a Python-only comment.
#[pyo3_doc_mode(end_doc_mode)]
pub mod pyo3_scratch {}

---

>>>> import pyo3_scratch
>>>> print(pyo3_scratch.__doc__)
A simple example of a native module with varying docs.

This is a Python-only comment.

---

One big drawback of this is that if the docs are placed above the attribute, which I'd consider normal Rust style, then the #[pyo3_doc_mode] attributes are evaluated before the #[pymodule] attribute, and this then causes compiler errors:

/// A simple example of a native module with varying docs.
///
#[pyo3_doc_mode(doc_mode = "rust")]
/// This is a Rust-only comment.
#[pyo3_doc_mode(doc_mode = "python")]
/// This is a Python-only comment.
#[pyo3_doc_mode(end_doc_mode)]
#[pyo3::pymodule]
pub mod pyo3_scratch {}

error: cannot find attribute `pyo3_doc_mode` in this scope
 --> src/lib.rs:3:3
  |
3 | #[pyo3_doc_mode(doc_mode = "rust")]
  |   ^^^^^^^^^^^^^

error: cannot find attribute `pyo3_doc_mode` in this scope
 --> src/lib.rs:5:3
  |
5 | #[pyo3_doc_mode(doc_mode = "python")]
  |   ^^^^^^^^^^^^^

error: cannot find attribute `pyo3_doc_mode` in this scope
 --> src/lib.rs:7:3
  |
7 | #[pyo3_doc_mode(end_doc_mode)]
  |   ^^^^^^^^^^^^^

error: could not document `pyo3-scratch`

We can probably improve the UX there so that an incorrect placement works better.

Or maybe there are other ideas entirely which are not placement sensitive?