From 75af678f4330db682e9ee99989a1bf7cdd4cbdd9 Mon Sep 17 00:00:00 2001 From: David Hewitt Date: Sat, 9 Mar 2024 21:10:58 +0100 Subject: [PATCH] docs: use kebab-case instead of snake_case for guide URLs (#3942) * guide: use kebab-case instead of snake_case * fixup doctest names Co-authored-by: Icxolu <10486322+Icxolu@users.noreply.github.com> * review: Icxolu * fix relative url * also remap latest pyo3 * fixup python_from_rust --------- Co-authored-by: Icxolu <10486322+Icxolu@users.noreply.github.com> --- .netlify/build.sh | 9 +++++++++ Architecture.md | 2 +- README.md | 4 ++-- build.rs | 2 +- ...ass_parameters.md => pyclass-parameters.md} | 0 guide/src/SUMMARY.md | 14 +++++++------- ...ibution.md => building-and-distribution.md} | 6 +++--- .../multiple-python-versions.md} | 2 +- guide/src/class.md | 2 +- guide/src/exception.md | 2 +- guide/src/features.md | 8 ++++---- .../{error_handling.md => error-handling.md} | 0 .../{getting_started.md => getting-started.md} | 4 ++-- guide/src/module.md | 2 +- ...python_from_rust.md => python-from-rust.md} | 0 ..._typing_hints.md => python-typing-hints.md} | 0 guide/src/{trait_bounds.md => trait-bounds.md} | 0 noxfile.py | 1 + pyo3-build-config/src/impl_.rs | 2 +- pyo3-build-config/src/lib.rs | 2 +- pyo3-ffi/README.md | 2 +- pyo3-ffi/src/lib.rs | 2 +- src/lib.rs | 18 +++++++++--------- 23 files changed, 47 insertions(+), 37 deletions(-) rename guide/{pyclass_parameters.md => pyclass-parameters.md} (100%) rename guide/src/{building_and_distribution.md => building-and-distribution.md} (99%) rename guide/src/{building_and_distribution/multiple_python_versions.md => building-and-distribution/multiple-python-versions.md} (98%) rename guide/src/function/{error_handling.md => error-handling.md} (100%) rename guide/src/{getting_started.md => getting-started.md} (92%) rename guide/src/{python_from_rust.md => python-from-rust.md} (100%) rename guide/src/{python_typing_hints.md => python-typing-hints.md} (100%) rename guide/src/{trait_bounds.md => trait-bounds.md} (100%) diff --git a/.netlify/build.sh b/.netlify/build.sh index dc68c031..e1d86788 100755 --- a/.netlify/build.sh +++ b/.netlify/build.sh @@ -48,6 +48,15 @@ done # Add latest redirect echo "/latest/* /v${PYO3_VERSION}/:splat 302" >> netlify_build/_redirects +# some backwards compatbiility redirects +echo "/latest/building_and_distribution/* /latest/building-and-distribution/:splat 302" >> netlify_build/_redirects +echo "/latest/building-and-distribution/multiple_python_versions/* /latest/building-and-distribution/multiple-python-versions:splat 302" >> netlify_build/_redirects +echo "/latest/function/error_handling/* /latest/function/error-handling/:splat 302" >> netlify_build/_redirects +echo "/latest/getting_started/* /latest/getting-started/:splat 302" >> netlify_build/_redirects +echo "/latest/python_from_rust/* /latest/python-from-rust/:splat 302" >> netlify_build/_redirects +echo "/latest/python_typing_hints/* /latest/python-typing-hints/:splat 302" >> netlify_build/_redirects +echo "/latest/trait_bounds/* /latest/trait-bounds/:splat 302" >> netlify_build/_redirects + ## Add landing page redirect if [ "${CONTEXT}" == "deploy-preview" ]; then echo "/ /main/" >> netlify_build/_redirects diff --git a/Architecture.md b/Architecture.md index 9ec20931..60083d71 100644 --- a/Architecture.md +++ b/Architecture.md @@ -48,7 +48,7 @@ In the [`pyo3-ffi`] crate, there is lots of conditional compilation such as `#[c `#[cfg(Py_3_7)]`, and `#[cfg(PyPy)]`. `Py_LIMITED_API` corresponds to `#define Py_LIMITED_API` macro in Python/C API. With `Py_LIMITED_API`, we can build a Python-version-agnostic binary called an -[abi3 wheel](https://pyo3.rs/latest/building_and_distribution.html#py_limited_apiabi3). +[abi3 wheel](https://pyo3.rs/latest/building-and-distribution.html#py_limited_apiabi3). `Py_3_7` means that the API is available from Python >= 3.7. There are also `Py_3_8`, `Py_3_9`, and so on. `PyPy` means that the API definition is for PyPy. diff --git a/README.md b/README.md index 21dc125d..c11754c3 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ 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. +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 @@ -162,7 +162,7 @@ fn main() -> PyResult<()> { } ``` -The guide has [a section](https://pyo3.rs/latest/python_from_rust.html) with lots of examples +The guide has [a section](https://pyo3.rs/latest/python-from-rust.html) with lots of examples about this topic. ## Tools and libraries diff --git a/build.rs b/build.rs index e2020631..7f0ae6e3 100644 --- a/build.rs +++ b/build.rs @@ -16,7 +16,7 @@ fn ensure_auto_initialize_ok(interpreter_config: &InterpreterConfig) -> Result<( \n\ For more information, see \ https://pyo3.rs/v{pyo3_version}/\ - building_and_distribution.html#embedding-python-in-rust", + building-and-distribution.html#embedding-python-in-rust", pyo3_version = env::var("CARGO_PKG_VERSION").unwrap() ); } diff --git a/guide/pyclass_parameters.md b/guide/pyclass-parameters.md similarity index 100% rename from guide/pyclass_parameters.md rename to guide/pyclass-parameters.md diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 34775a0d..6aea71b1 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -4,11 +4,11 @@ --- -- [Getting started](getting_started.md) +- [Getting started](getting-started.md) - [Python modules](module.md) - [Python functions](function.md) - [Function signatures](function/signature.md) - - [Error handling](function/error_handling.md) + - [Error handling](function/error-handling.md) - [Python classes](class.md) - [Class customizations](class/protocols.md) - [Basic object customization](class/object.md) @@ -18,7 +18,7 @@ - [Mapping of Rust types to Python types](conversions/tables.md) - [Conversion traits](conversions/traits.md) - [Python exceptions](exception.md) -- [Calling Python from Rust](python_from_rust.md) +- [Calling Python from Rust](python-from-rust.md) - [Using `async` and `await`](async-await.md) - [GIL, mutability and object types](types.md) - [Parallelism](parallelism.md) @@ -27,8 +27,8 @@ - [Memory management](memory.md) - [Performance](performance.md) - [Advanced topics](advanced.md) -- [Building and distribution](building_and_distribution.md) - - [Supporting multiple Python versions](building_and_distribution/multiple_python_versions.md) +- [Building and distribution](building-and-distribution.md) + - [Supporting multiple Python versions](building-and-distribution/multiple-python-versions.md) - [Useful crates](ecosystem.md) - [Logging](ecosystem/logging.md) - [Using `async` and `await`](ecosystem/async-await.md) @@ -37,8 +37,8 @@ --- [Appendix A: Migration guide](migration.md) -[Appendix B: Trait bounds](trait_bounds.md) -[Appendix C: Python typing hints](python_typing_hints.md) +[Appendix B: Trait bounds](trait-bounds.md) +[Appendix C: Python typing hints](python-typing-hints.md) [CHANGELOG](changelog.md) --- diff --git a/guide/src/building_and_distribution.md b/guide/src/building-and-distribution.md similarity index 99% rename from guide/src/building_and_distribution.md rename to guide/src/building-and-distribution.md index 8caa63e6..780f135e 100644 --- a/guide/src/building_and_distribution.md +++ b/guide/src/building-and-distribution.md @@ -4,7 +4,7 @@ This chapter of the guide goes into detail on how to build and distribute projec The material in this chapter is intended for users who have already read the PyO3 [README](./index.md). It covers in turn the choices that can be made for Python modules and for Rust binaries. There is also a section at the end about cross-compiling projects using PyO3. -There is an additional sub-chapter dedicated to [supporting multiple Python versions](./building_and_distribution/multiple_python_versions.md). +There is an additional sub-chapter dedicated to [supporting multiple Python versions](./building-and-distribution/multiple-python-versions.md). ## Configuring the Python version @@ -177,7 +177,7 @@ The downside of not linking to `libpython` is that binaries, tests, and examples By default, Python extension modules can only be used with the same Python version they were compiled against. For example, an extension module built for Python 3.5 can't be imported in Python 3.8. [PEP 384](https://www.python.org/dev/peps/pep-0384/) introduced the idea of the limited Python API, which would have a stable ABI enabling extension modules built with it to be used against multiple Python versions. This is also known as `abi3`. -The advantage of building extension modules using the limited Python API is that package vendors only need to build and distribute a single copy (for each OS / architecture), and users can install it on all Python versions from the [minimum version](#minimum-python-version-for-abi3) and up. The downside of this is that PyO3 can't use optimizations which rely on being compiled against a known exact Python version. It's up to you to decide whether this matters for your extension module. It's also possible to design your extension module such that you can distribute `abi3` wheels but allow users compiling from source to benefit from additional optimizations - see the [support for multiple python versions](./building_and_distribution/multiple_python_versions.md) section of this guide, in particular the `#[cfg(Py_LIMITED_API)]` flag. +The advantage of building extension modules using the limited Python API is that package vendors only need to build and distribute a single copy (for each OS / architecture), and users can install it on all Python versions from the [minimum version](#minimum-python-version-for-abi3) and up. The downside of this is that PyO3 can't use optimizations which rely on being compiled against a known exact Python version. It's up to you to decide whether this matters for your extension module. It's also possible to design your extension module such that you can distribute `abi3` wheels but allow users compiling from source to benefit from additional optimizations - see the [support for multiple python versions](./building-and-distribution/multiple-python-versions.md) section of this guide, in particular the `#[cfg(Py_LIMITED_API)]` flag. There are three steps involved in making use of `abi3` when building Python packages as wheels: @@ -198,7 +198,7 @@ See the [corresponding](https://github.com/PyO3/maturin/pull/353) [PRs](https:// Because a single `abi3` wheel can be used with many different Python versions, PyO3 has feature flags `abi3-py37`, `abi3-py38`, `abi3-py39` etc. to set the minimum required Python version for your `abi3` wheel. For example, if you set the `abi3-py37` feature, your extension wheel can be used on all Python 3 versions from Python 3.7 and up. `maturin` and `setuptools-rust` will give the wheel a name like `my-extension-1.0-cp37-abi3-manylinux2020_x86_64.whl`. -As your extension module may be run with multiple different Python versions you may occasionally find you need to check the Python version at runtime to customize behavior. See [the relevant section of this guide](./building_and_distribution/multiple_python_versions.md#checking-the-python-version-at-runtime) on supporting multiple Python versions at runtime. +As your extension module may be run with multiple different Python versions you may occasionally find you need to check the Python version at runtime to customize behavior. See [the relevant section of this guide](./building-and-distribution/multiple-python-versions.md#checking-the-python-version-at-runtime) on supporting multiple Python versions at runtime. PyO3 is only able to link your extension module to abi3 version up to and including your host Python version. E.g., if you set `abi3-py38` and try to compile the crate with a host of Python 3.7, the build will fail. diff --git a/guide/src/building_and_distribution/multiple_python_versions.md b/guide/src/building-and-distribution/multiple-python-versions.md similarity index 98% rename from guide/src/building_and_distribution/multiple_python_versions.md rename to guide/src/building-and-distribution/multiple-python-versions.md index 4e1799a2..b328d236 100644 --- a/guide/src/building_and_distribution/multiple_python_versions.md +++ b/guide/src/building-and-distribution/multiple-python-versions.md @@ -85,7 +85,7 @@ This `#[cfg]` marks code which is running on PyPy. ## Checking the Python version at runtime -When building with PyO3's `abi3` feature, your extension module will be compiled against a specific [minimum version](../building_and_distribution.md#minimum-python-version-for-abi3) of Python, but may be running on newer Python versions. +When building with PyO3's `abi3` feature, your extension module will be compiled against a specific [minimum version](../building-and-distribution.md#minimum-python-version-for-abi3) of Python, but may be running on newer Python versions. For example with PyO3's `abi3-py38` feature, your extension will be compiled as if it were for Python 3.8. If you were using `pyo3-build-config`, `#[cfg(Py_3_8)]` would be present. Your user could freely install and run your abi3 extension on Python 3.9. diff --git a/guide/src/class.md b/guide/src/class.md index bfcdc108..93920a40 100644 --- a/guide/src/class.md +++ b/guide/src/class.md @@ -288,7 +288,7 @@ Frozen classes are likely to become the default thereby guiding the PyO3 ecosyst ## Customizing the class -{{#include ../pyclass_parameters.md}} +{{#include ../pyclass-parameters.md}} These parameters are covered in various sections of this guide. diff --git a/guide/src/exception.md b/guide/src/exception.md index 9e8cb780..ee36f544 100644 --- a/guide/src/exception.md +++ b/guide/src/exception.md @@ -54,7 +54,7 @@ fn mymodule(py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> { ## Raising an exception -As described in the [function error handling](./function/error_handling.md) chapter, to raise an exception from a `#[pyfunction]` or `#[pymethods]`, return an `Err(PyErr)`. PyO3 will automatically raise this exception for you when returning the result to Python. +As described in the [function error handling](./function/error-handling.md) chapter, to raise an exception from a `#[pyfunction]` or `#[pymethods]`, return an `Err(PyErr)`. PyO3 will automatically raise this exception for you when returning the result to Python. You can also manually write and fetch errors in the Python interpreter's global state: diff --git a/guide/src/features.md b/guide/src/features.md index 3ee62072..6e4e5ab7 100644 --- a/guide/src/features.md +++ b/guide/src/features.md @@ -12,7 +12,7 @@ This feature is required when building a Python extension module using PyO3. It tells PyO3's build script to skip linking against `libpython.so` on Unix platforms, where this must not be done. -See the [building and distribution](building_and_distribution.md#the-extension-module-feature) section for further detail. +See the [building and distribution](building-and-distribution.md#the-extension-module-feature) section for further detail. ### `abi3` @@ -20,7 +20,7 @@ This feature is used when building Python extension modules to create wheels whi It restricts PyO3's API to a subset of the full Python API which is guaranteed by [PEP 384](https://www.python.org/dev/peps/pep-0384/) to be forwards-compatible with future Python versions. -See the [building and distribution](building_and_distribution.md#py_limited_apiabi3) section for further detail. +See the [building and distribution](building-and-distribution.md#py_limited_apiabi3) section for further detail. ### The `abi3-pyXY` features @@ -28,7 +28,7 @@ See the [building and distribution](building_and_distribution.md#py_limited_apia These features are extensions of the `abi3` feature to specify the exact minimum Python version which the multiple-version-wheel will support. -See the [building and distribution](building_and_distribution.md#minimum-python-version-for-abi3) section for further detail. +See the [building and distribution](building-and-distribution.md#minimum-python-version-for-abi3) section for further detail. ### `generate-import-lib` @@ -38,7 +38,7 @@ for MinGW-w64 and MSVC (cross-)compile targets. Enabling it allows to (cross-)compile extension modules to any Windows targets without having to install the Windows Python distribution files for the target. -See the [building and distribution](building_and_distribution.md#building-abi3-extensions-without-a-python-interpreter) +See the [building and distribution](building-and-distribution.md#building-abi3-extensions-without-a-python-interpreter) section for further detail. ## Features for embedding Python in Rust diff --git a/guide/src/function/error_handling.md b/guide/src/function/error-handling.md similarity index 100% rename from guide/src/function/error_handling.md rename to guide/src/function/error-handling.md diff --git a/guide/src/getting_started.md b/guide/src/getting-started.md similarity index 92% rename from guide/src/getting_started.md rename to guide/src/getting-started.md index 008da810..ef9ca525 100644 --- a/guide/src/getting_started.md +++ b/guide/src/getting-started.md @@ -33,7 +33,7 @@ You can read more about `pyenv`'s configuration options [here](https://github.co ### Building -There are a number of build and Python package management systems such as [`setuptools-rust`](https://github.com/PyO3/setuptools-rust) or [manually](https://pyo3.rs/latest/building_and_distribution.html#manual-builds). We recommend the use of `maturin`, which you can install [here](https://maturin.rs/installation.html). It is developed to work with PyO3 and provides the most "batteries included" experience, especially if you are aiming to publish to PyPI. `maturin` is just a Python package, so you can add it in the same you already install Python packages. +There are a number of build and Python package management systems such as [`setuptools-rust`](https://github.com/PyO3/setuptools-rust) or [manually](./building-and-distribution.md#manual-builds). We recommend the use of `maturin`, which you can install [here](https://maturin.rs/installation.html). It is developed to work with PyO3 and provides the most "batteries included" experience, especially if you are aiming to publish to PyPI. `maturin` is just a Python package, so you can add it in the same you already install Python packages. System Python: ```bash @@ -180,4 +180,4 @@ $ python '25' ``` -For more instructions on how to use Python code from Rust, see the [Python from Rust](python_from_rust.md) page. +For more instructions on how to use Python code from Rust, see the [Python from Rust](python-from-rust.md) page. diff --git a/guide/src/module.md b/guide/src/module.md index 410716fd..8cac9a5b 100644 --- a/guide/src/module.md +++ b/guide/src/module.md @@ -45,7 +45,7 @@ file. Otherwise, you will get an import error in Python with the following messa `ImportError: dynamic module does not define module export function (PyInit_name_of_your_module)` To import the module, either: - - copy the shared library as described in [Manual builds](building_and_distribution.md#manual-builds), or + - copy the shared library as described in [Manual builds](building-and-distribution.md#manual-builds), or - use a tool, e.g. `maturin develop` with [maturin](https://github.com/PyO3/maturin) or `python setup.py develop` with [setuptools-rust](https://github.com/PyO3/setuptools-rust). diff --git a/guide/src/python_from_rust.md b/guide/src/python-from-rust.md similarity index 100% rename from guide/src/python_from_rust.md rename to guide/src/python-from-rust.md diff --git a/guide/src/python_typing_hints.md b/guide/src/python-typing-hints.md similarity index 100% rename from guide/src/python_typing_hints.md rename to guide/src/python-typing-hints.md diff --git a/guide/src/trait_bounds.md b/guide/src/trait-bounds.md similarity index 100% rename from guide/src/trait_bounds.md rename to guide/src/trait-bounds.md diff --git a/noxfile.py b/noxfile.py index 29fe0f91..f70fced7 100644 --- a/noxfile.py +++ b/noxfile.py @@ -417,6 +417,7 @@ def check_guide(session: nox.Session): "lychee", PYO3_DOCS_TARGET, f"--remap=https://pyo3.rs/main/ file://{PYO3_GUIDE_TARGET}/", + f"--remap=https://pyo3.rs/latest/ file://{PYO3_GUIDE_TARGET}/", f"--exclude=file://{PYO3_DOCS_TARGET}", *session.posargs, ) diff --git a/pyo3-build-config/src/impl_.rs b/pyo3-build-config/src/impl_.rs index 698c58a1..7f02f744 100644 --- a/pyo3-build-config/src/impl_.rs +++ b/pyo3-build-config/src/impl_.rs @@ -1365,7 +1365,7 @@ fn default_cross_compile(cross_compile_config: &CrossCompileConfig) -> Result "Documentation about the `serde` feature." -//! [calling_rust]: https://pyo3.rs/latest/python_from_rust.html "Calling Python from Rust - PyO3 user guide" +//! [calling_rust]: https://pyo3.rs/latest/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" +//! [manual_builds]: https://pyo3.rs/latest/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 //! [serde]: https://docs.rs/serde @@ -453,7 +453,7 @@ pub use pyo3_macros::{pyfunction, pymethods, pymodule, FromPyObject}; /// A proc macro used to expose Rust structs and fieldless enums as Python objects. /// -#[doc = include_str!("../guide/pyclass_parameters.md")] +#[doc = include_str!("../guide/pyclass-parameters.md")] /// /// For more on creating Python classes, /// see the [class section of the guide][1]. @@ -485,8 +485,8 @@ pub mod doc_test { "README.md" => readme_md, "guide/src/advanced.md" => guide_advanced_md, "guide/src/async-await.md" => guide_async_await_md, - "guide/src/building_and_distribution.md" => guide_building_and_distribution_md, - "guide/src/building_and_distribution/multiple_python_versions.md" => guide_bnd_multiple_python_versions_md, + "guide/src/building-and-distribution.md" => guide_building_and_distribution_md, + "guide/src/building-and-distribution/multiple-python-versions.md" => guide_bnd_multiple_python_versions_md, "guide/src/class.md" => guide_class_md, "guide/src/class/call.md" => guide_class_call, "guide/src/class/object.md" => guide_class_object, @@ -504,16 +504,16 @@ pub mod doc_test { "guide/src/faq.md" => guide_faq_md, "guide/src/features.md" => guide_features_md, "guide/src/function.md" => guide_function_md, - "guide/src/function/error_handling.md" => guide_function_error_handling_md, + "guide/src/function/error-handling.md" => guide_function_error_handling_md, "guide/src/function/signature.md" => guide_function_signature_md, "guide/src/memory.md" => guide_memory_md, "guide/src/migration.md" => guide_migration_md, "guide/src/module.md" => guide_module_md, "guide/src/parallelism.md" => guide_parallelism_md, "guide/src/performance.md" => guide_performance_md, - "guide/src/python_from_rust.md" => guide_python_from_rust_md, - "guide/src/python_typing_hints.md" => guide_python_typing_hints_md, - "guide/src/trait_bounds.md" => guide_trait_bounds_md, + "guide/src/python-from-rust.md" => guide_python_from_rust_md, + "guide/src/python-typing-hints.md" => guide_python_typing_hints_md, + "guide/src/trait-bounds.md" => guide_trait_bounds_md, "guide/src/types.md" => guide_types_md, } }