docs: use versioned links from docs to guide (#4331)

* use versioned links from docs to guide

* use standard python version in `guide-build` ci job

Author: davidhewitt

.github/workflows/gh-pages.yml

@@ -22,7 +22,7 @@ jobs:
       tag_name: ${{ steps.prepare_tag.outputs.tag_name }}
     steps:
       - uses: actions/checkout@v4
-
+      - uses: actions/setup-python@v5
       - uses: dtolnay/rust-toolchain@nightly
 
       - name: Setup mdBook

guide/src/building-and-distribution.md

@@ -163,7 +163,7 @@ fn main() {
 
 For more discussion on and workarounds for MacOS linking problems [see this issue](https://github.com/PyO3/pyo3/issues/1800#issuecomment-906786649).
 
-Finally, don't forget that on MacOS the `extension-module` feature will cause `cargo test` to fail without the `--no-default-features` flag (see [the FAQ](https://pyo3.rs/main/faq.html#i-cant-run-cargo-test-im-having-linker-issues-like-symbol-not-found-or-undefined-reference-to-_pyexc_systemerror)).
+Finally, don't forget that on MacOS the `extension-module` feature will cause `cargo test` to fail without the `--no-default-features` flag (see [the FAQ](https://pyo3.rs/main/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)).
 
 ### The `extension-module` feature
 

noxfile.py

@@ -394,8 +394,17 @@ def check_guide(session: nox.Session):
     docs(session)
     session.posargs.extend(posargs)
 
+    if toml is None:
+        session.error("requires Python 3.11 or `toml` to be installed")
+    pyo3_version = toml.loads((PYO3_DIR / "Cargo.toml").read_text())["package"][
+        "version"
+    ]
+
     remaps = {
         f"file://{PYO3_GUIDE_SRC}/([^/]*/)*?%7B%7B#PYO3_DOCS_URL}}}}": f"file://{PYO3_DOCS_TARGET}",
+        f"https://pyo3.rs/v{pyo3_version}": f"file://{PYO3_GUIDE_TARGET}",
+        "https://pyo3.rs/main/": f"file://{PYO3_GUIDE_TARGET}/",
+        "https://pyo3.rs/latest/": f"file://{PYO3_GUIDE_TARGET}/",
         "%7B%7B#PYO3_DOCS_VERSION}}": "latest",
     }
     remap_args = []
@@ -416,8 +425,7 @@ def check_guide(session: nox.Session):
         session,
         "lychee",
         str(PYO3_DOCS_TARGET),
-        f"--remap=https://pyo3.rs/main/ file://{PYO3_GUIDE_TARGET}/",
-        f"--remap=https://pyo3.rs/latest/ file://{PYO3_GUIDE_TARGET}/",
+        *remap_args,
         f"--exclude=file://{PYO3_DOCS_TARGET}",
         "--exclude=http://www.adobe.com/",
         *session.posargs,

pyo3-build-config/src/lib.rs

@@ -39,7 +39,9 @@ use target_lexicon::OperatingSystem;
 /// | `#[cfg(PyPy)]` | This marks code which is run when compiling for PyPy. |
 /// | `#[cfg(GraalPy)]` | This marks code which is run when compiling for GraalPy. |
 ///
-/// For examples of how to use these attributes, [see PyO3's guide](https://pyo3.rs/latest/building-and-distribution/multiple_python_versions.html).
+/// For examples of how to use these attributes,
+#[doc = concat!("[see PyO3's guide](https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/building-and-distribution/multiple_python_versions.html)")]
+/// .
 #[cfg(feature = "resolve-config")]
 pub fn use_pyo3_cfgs() {
     print_expected_cfgs();

pyo3-ffi/src/lib.rs

@@ -221,11 +221,10 @@
 //! [`maturin`]: https://github.com/PyO3/maturin "Build and publish crates with pyo3, rust-cpython and cffi bindings as well as rust binaries as python packages"
 //! [`pyo3-build-config`]: https://docs.rs/pyo3-build-config
 //! [feature flags]: https://doc.rust-lang.org/cargo/reference/features.html "Features - The Cargo Book"
-//! [manual_builds]: https://pyo3.rs/latest/building-and-distribution.html#manual-builds "Manual builds - Building and Distribution - PyO3 user guide"
+#![doc = concat!("[manual_builds]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/building-and-distribution.html#manual-builds \"Manual builds - Building and Distribution - PyO3 user guide\"")]
 //! [setuptools-rust]: https://github.com/PyO3/setuptools-rust "Setuptools plugin for Rust extensions"
 //! [PEP 384]: https://www.python.org/dev/peps/pep-0384 "PEP 384 -- Defining a Stable ABI"
-//! [Features chapter of the guide]: https://pyo3.rs/latest/features.html#features-reference "Features Reference - PyO3 user guide"
-
+#![doc = concat!("[Features chapter of the guide]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/features.html#features-reference \"Features Reference - PyO3 user guide\"")]
 #![allow(
     missing_docs,
     non_camel_case_types,

pyo3-macros-backend/src/pyclass.rs

@@ -232,17 +232,19 @@ pub fn build_py_class(
 
     if let Some(lt) = class.generics.lifetimes().next() {
         bail_spanned!(
-            lt.span() =>
-            "#[pyclass] cannot have lifetime parameters. \
-            For an explanation, see https://pyo3.rs/latest/class.html#no-lifetime-parameters"
+            lt.span() => concat!(
+                "#[pyclass] cannot have lifetime parameters. For an explanation, see \
+                https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#no-lifetime-parameters"
+            )
         );
     }
 
     ensure_spanned!(
         class.generics.params.is_empty(),
-        class.generics.span() =>
-            "#[pyclass] cannot have generic parameters. \
-            For an explanation, see https://pyo3.rs/latest/class.html#no-generic-parameters"
+        class.generics.span() => concat!(
+            "#[pyclass] cannot have generic parameters. For an explanation, see \
+            https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#no-generic-parameters"
+        )
     );
 
     let mut field_options: Vec<(&syn::Field, FieldPyO3Options)> = match &mut class.fields {

pyo3-macros/src/lib.rs

@@ -32,7 +32,7 @@ use syn::{parse::Nothing, parse_macro_input, Item};
 /// `#[pymodule]` implementation generates a hidden module with the same name containing
 /// metadata about the module, which is used by `wrap_pymodule!`).
 ///
-/// [1]: https://pyo3.rs/latest/module.html
+#[doc = concat!("[1]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/module.html")]
 #[proc_macro_attribute]
 pub fn pymodule(args: TokenStream, input: TokenStream) -> TokenStream {
     match parse_macro_input!(input as Item) {
@@ -99,17 +99,17 @@ pub fn pyclass(attr: TokenStream, input: TokenStream) -> TokenStream {
 /// multiple `#[pymethods]` blocks for a single `#[pyclass]`.
 /// This will add a transitive dependency on the [`inventory`][3] crate.
 ///
-/// [1]: https://pyo3.rs/latest/class.html#instance-methods
-/// [2]: https://pyo3.rs/latest/features.html#multiple-pymethods
+#[doc = concat!("[1]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#instance-methods")]
+#[doc = concat!("[2]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/features.html#multiple-pymethods")]
 /// [3]: https://docs.rs/inventory/
-/// [4]: https://pyo3.rs/latest/class.html#constructor
-/// [5]: https://pyo3.rs/latest/class.html#object-properties-using-getter-and-setter
-/// [6]: https://pyo3.rs/latest/class.html#static-methods
-/// [7]: https://pyo3.rs/latest/class.html#class-methods
-/// [8]: https://pyo3.rs/latest/class.html#callable-objects
-/// [9]: https://pyo3.rs/latest/class.html#class-attributes
-/// [10]: https://pyo3.rs/latest/class.html#method-arguments
-/// [11]: https://pyo3.rs/latest/class.html#object-properties-using-pyo3get-set
+#[doc = concat!("[4]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#constructor")]
+#[doc = concat!("[5]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#object-properties-using-getter-and-setter")]
+#[doc = concat!("[6]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#static-methods")]
+#[doc = concat!("[7]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#class-methods")]
+#[doc = concat!("[8]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#callable-objects")]
+#[doc = concat!("[9]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#class-attributes")]
+#[doc = concat!("[10]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#method-arguments")]
+#[doc = concat!("[11]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#object-properties-using-pyo3get-set")]
 #[proc_macro_attribute]
 pub fn pymethods(attr: TokenStream, input: TokenStream) -> TokenStream {
     let methods_type = if cfg!(feature = "multiple-pymethods") {
@@ -138,7 +138,7 @@ pub fn pymethods(attr: TokenStream, input: TokenStream) -> TokenStream {
 /// `#[pyfunction]` implementation generates a hidden module with the same name containing
 /// metadata about the function, which is used by `wrap_pyfunction!`).
 ///
-/// [1]: https://pyo3.rs/latest/function.html
+#[doc = concat!("[1]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/function.html")]
 #[proc_macro_attribute]
 pub fn pyfunction(attr: TokenStream, input: TokenStream) -> TokenStream {
     let mut ast = parse_macro_input!(input as syn::ItemFn);

src/instance.rs

@@ -744,7 +744,8 @@ impl<T> IntoPy<PyObject> for Borrowed<'_, '_, T> {
 ///  - [`Py::borrow`], [`Py::try_borrow`], [`Py::borrow_mut`], or [`Py::try_borrow_mut`],
 ///
 /// to get a (mutable) reference to a contained pyclass, using a scheme similar to std's [`RefCell`].
-/// See the [guide entry](https://pyo3.rs/latest/class.html#bound-and-interior-mutability)
+/// See the
+#[doc = concat!("[guide entry](https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#bound-and-interior-mutability)")]
 /// for more information.
 ///  - You can call methods directly on `Py` with [`Py::call_bound`], [`Py::call_method_bound`] and friends.
 ///

src/lib.rs

@@ -295,25 +295,25 @@
 //! [`rust_decimal`]: ./rust_decimal/index.html "Documenation about the `rust_decimal` feature."
 //! [`Decimal`]: https://docs.rs/rust_decimal/latest/rust_decimal/struct.Decimal.html
 //! [`serde`]: <./serde/index.html> "Documentation about the `serde` feature."
-//! [calling_rust]: https://pyo3.rs/latest/python-from-rust.html "Calling Python from Rust - PyO3 user guide"
+#![doc = concat!("[calling_rust]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/python-from-rust.html \"Calling Python from Rust - PyO3 user guide\"")]
 //! [examples subdirectory]: https://github.com/PyO3/pyo3/tree/main/examples
 //! [feature flags]: https://doc.rust-lang.org/cargo/reference/features.html "Features - The Cargo Book"
 //! [global interpreter lock]: https://docs.python.org/3/glossary.html#term-global-interpreter-lock
 //! [hashbrown]: https://docs.rs/hashbrown
 //! [smallvec]: https://docs.rs/smallvec
 //! [indexmap]: https://docs.rs/indexmap
-//! [manual_builds]: https://pyo3.rs/latest/building-and-distribution.html#manual-builds "Manual builds - Building and Distribution - PyO3 user guide"
+#![doc = concat!("[manual_builds]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/building-and-distribution.html#manual-builds \"Manual builds - Building and Distribution - PyO3 user guide\"")]
 //! [num-bigint]: https://docs.rs/num-bigint
 //! [num-complex]: https://docs.rs/num-complex
 //! [num-rational]: https://docs.rs/num-rational
 //! [serde]: https://docs.rs/serde
 //! [setuptools-rust]: https://github.com/PyO3/setuptools-rust "Setuptools plugin for Rust extensions"
 //! [the guide]: https://pyo3.rs "PyO3 user guide"
-//! [types]: https://pyo3.rs/latest/types.html "GIL lifetimes, mutability and Python object types"
+#![doc = concat!("[types]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/types.html \"GIL lifetimes, mutability and Python object types\"")]
 //! [PEP 384]: https://www.python.org/dev/peps/pep-0384 "PEP 384 -- Defining a Stable ABI"
 //! [Python from Rust]: https://github.com/PyO3/pyo3#using-python-from-rust
 //! [Rust from Python]: https://github.com/PyO3/pyo3#using-rust-from-python
-//! [Features chapter of the guide]: https://pyo3.rs/latest/features.html#features-reference "Features Reference - PyO3 user guide"
+#![doc = concat!("[Features chapter of the guide]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/features.html#features-reference \"Features Reference - PyO3 user guide\"")]
 //! [`Ungil`]: crate::marker::Ungil
 pub use crate::class::*;
 pub use crate::conversion::{AsPyPointer, FromPyObject, IntoPy, ToPyObject};
@@ -483,7 +483,7 @@ pub use pyo3_macros::{pyfunction, pymethods, pymodule, FromPyObject};
 /// For more on creating Python classes,
 /// see the [class section of the guide][1].
 ///
-/// [1]: https://pyo3.rs/latest/class.html
+#[doc = concat!("[1]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html")]
 #[cfg(feature = "macros")]
 pub use pyo3_macros::pyclass;
 

src/sync.rs

@@ -59,7 +59,9 @@ unsafe impl<T> Sync for GILProtected<T> where T: Send {}
 /// Unlike `once_cell::sync` which blocks threads to achieve thread safety, this implementation
 /// uses the Python GIL to mediate concurrent access. This helps in cases where `once_cell` or
 /// `lazy_static`'s synchronization strategy can lead to deadlocks when interacting with the Python
-/// GIL. For an example, see [the FAQ section](https://pyo3.rs/latest/faq.html) of the guide.
+/// GIL. For an example, see
+#[doc = concat!("[the FAQ section](https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/faq.html)")]
+/// of the guide.
 ///
 /// Note that:
 ///  1) `get_or_init` and `get_or_try_init` do not protect against infinite recursion

src/types/module.rs

@@ -304,7 +304,7 @@ impl PyModule {
     /// make an *instance* of `Foo` (or *get* one for that matter, as we haven't exported
     /// anything that can return instances of `Foo`).
     ///
-    /// [1]: https://pyo3.rs/latest/class.html#constructor
+    #[doc = concat!("[1]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#constructor")]
     pub fn add_class<T>(&self) -> PyResult<()>
     where
         T: PyClass,
@@ -509,7 +509,7 @@ pub trait PyModuleMethods<'py>: crate::sealed::Sealed {
     /// make an *instance* of `Foo` (or *get* one for that matter, as we haven't exported
     /// anything that can return instances of `Foo`).
     ///
-    /// [1]: https://pyo3.rs/latest/class.html#constructor
+    #[doc = concat!("[1]: https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/class.html#constructor")]
     fn add_class<T>(&self) -> PyResult<()>
     where
         T: PyClass;

tests/ui/reject_generics.stderr

@@ -1,10 +1,10 @@
-error: #[pyclass] cannot have generic parameters. For an explanation, see https://pyo3.rs/latest/class.html#no-generic-parameters
+error: #[pyclass] cannot have generic parameters. For an explanation, see https://pyo3.rs/v0.23.0-dev/class.html#no-generic-parameters
  --> tests/ui/reject_generics.rs:4:25
   |
 4 | struct ClassWithGenerics<A> {
   |                         ^
 
-error: #[pyclass] cannot have lifetime parameters. For an explanation, see https://pyo3.rs/latest/class.html#no-lifetime-parameters
+error: #[pyclass] cannot have lifetime parameters. For an explanation, see https://pyo3.rs/v0.23.0-dev/class.html#no-lifetime-parameters
  --> tests/ui/reject_generics.rs:9:27
   |
 9 | struct ClassWithLifetimes<'a> {