Add documentation for more workarounds for enabling the extension-module feature

Closes https://github.com/PyO3/pyo3/issues/2521

README.md

@@ -116,6 +116,8 @@ maturin init --bindings pyo3
 maturin develop
 ```
 
+If you want to be able to run `cargo test` or use this project in a Cargo workspace and are running into linker issues, there are some workarounds in [the FAQ](https://pyo3.rs/latest/faq.html#i-cant-run-cargo-test-or-i-cant-build-in-a-cargo-workspace-im-having-linker-issues-like-symbol-not-found-or-undefined-reference-to-_pyexc_systemerror).
+
 As well as with `maturin`, it is possible to build using [`setuptools-rust`](https://github.com/PyO3/setuptools-rust) or [manually](https://pyo3.rs/latest/building_and_distribution.html#manual-builds). Both offer more flexibility than `maturin` but require more configuration to get started.
 
 ### Using Python from Rust

guide/src/building_and_distribution.md

@@ -141,7 +141,7 @@ PyO3's `extension-module` feature is used to disable [linking](https://en.wikipe
 
 This is necessary because by default PyO3 links to `libpython`. This makes binaries, tests, and examples "just work". However, Python extensions on unix must not link to libpython for [manylinux](https://www.python.org/dev/peps/pep-0513/) compliance.
 
-The downside of not linking to `libpython` is that binaries, tests, and examples (which usually embed Python) will fail to build. If you have an extension module as well as other outputs in a single project, you need to use optional Cargo features to disable the `extension-module` when you're not building the extension module. See [the FAQ](faq.md#i-cant-run-cargo-test-im-having-linker-issues-like-symbol-not-found-or-undefined-reference-to-_pyexc_systemerror) for an example workaround.
+The downside of not linking to `libpython` is that binaries, tests, and examples (which usually embed Python) will fail to build. If you have an extension module as well as other outputs in a single project, you need to use optional Cargo features to disable the `extension-module` when you're not building the extension module. See [the FAQ](faq.md#i-cant-run-cargo-test-or-i-cant-build-in-a-cargo-workspace-im-having-linker-issues-like-symbol-not-found-or-undefined-reference-to-_pyexc_systemerror) for an example workaround.
 
 ### `Py_LIMITED_API`/`abi3`
 

guide/src/faq.md

@@ -15,9 +15,21 @@ PyO3 provides a struct [`GILOnceCell`] which works equivalently to `OnceCell` bu
 
 [`GILOnceCell`]: {{#PYO3_DOCS_URL}}/pyo3/once_cell/struct.GILOnceCell.html
 
-## I can't run `cargo test`: I'm having linker issues like "Symbol not found" or "Undefined reference to _PyExc_SystemError"!
+## I can't run `cargo test`; or I can't build in a Cargo workspace: I'm having linker issues like "Symbol not found" or "Undefined reference to _PyExc_SystemError"!
 
-Currently, [#340](https://github.com/PyO3/pyo3/issues/340) causes `cargo test` to fail with linking errors when the `extension-module` feature is activated. For now you can work around this by making the `extension-module` feature optional and running the tests with `cargo test --no-default-features`:
+Currently, [#340](https://github.com/PyO3/pyo3/issues/340) causes `cargo test` to fail with linking errors when the `extension-module` feature is activated. Linking errors can also happen when building in a cargo workspace where a different crate also uses PyO3 (see [#2521](https://github.com/PyO3/pyo3/issues/2521)). For now, there are three ways we can work around these issues.
+
+1. Make the `extension-module` feature optional. Build with `maturin develop --features "extension-module"`
+
+```toml
+[dependencies.pyo3]
+{{#PYO3_CRATE_VERSION}}
+
+[features]
+extension-module = ["pyo3/extension-module"]
+```
+
+2. Make the `extension-module` feature optional and default. Run tests with `cargo test --no-default-features`:
 
 ```toml
 [dependencies.pyo3]
@@ -28,6 +40,15 @@ extension-module = ["pyo3/extension-module"]
 default = ["extension-module"]
 ```
 
+3. If you are using a [`pyproject.toml`](https://maturin.rs/metadata.html) file to control maturin settings, add the following section:
+
+```toml
+[tool.maturin]
+features = ["pyo3/extension-module"]
+# Or for maturin 0.12:
+# cargo-extra-args = ["--features", "pyo3/extension-module"]
+```
+
 ## I can't run `cargo test`: my crate cannot be found for tests in `tests/` directory!
 
 The Rust book suggests to [put integration tests inside a `tests/` directory](https://doc.rust-lang.org/book/ch11-03-test-organization.html#integration-tests).