From 6afd80a26f2b7ef99247369041ec5fc2c96ebeb1 Mon Sep 17 00:00:00 2001 From: mejrs Date: Wed, 22 Dec 2021 12:09:16 +0100 Subject: [PATCH 1/5] Create full feature and change doc rendering --- .cargo/config.toml | 7 +++++++ .github/workflows/ci.yml | 26 ++++++++++---------------- .github/workflows/guide.yml | 28 +++++++++++++++++++++++++--- Cargo.toml | 4 ++++ Contributing.md | 11 +++++++---- pyo3-macros-backend/src/lib.rs | 2 +- pyo3-macros-backend/src/method.rs | 12 ++++++------ pyo3-macros/src/lib.rs | 2 +- src/conversions/anyhow.rs | 7 ++++--- src/conversions/eyre.rs | 4 +++- src/internal_tricks.rs | 3 ++- 11 files changed, 70 insertions(+), 36 deletions(-) create mode 100644 .cargo/config.toml diff --git a/.cargo/config.toml b/.cargo/config.toml new file mode 100644 index 00000000000..b3627e04e9a --- /dev/null +++ b/.cargo/config.toml @@ -0,0 +1,7 @@ +[alias] +pyo3_doc = "doc --lib --no-default-features --features=full --no-deps --workspace --open --exclude pyo3-macros --exclude pyo3-macros-backend" +pyo3_doc_scrape = "doc --lib --no-default-features --features=full --no-deps --workspace --open --exclude pyo3-macros --exclude pyo3-macros-backend -Z unstable-options -Z rustdoc-scrape-examples=examples" +pyo3_doc_internal = "doc --lib --no-default-features --features=full --no-deps --workspace --open --document-private-items -Z unstable-options -Z rustdoc-scrape-examples=examples" + +[build] +rustdocflags = ["--cfg", "docsrs"] diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index afffe8745b4..5ae04472c52 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -64,8 +64,8 @@ jobs: echo "suppress_build_script_link_lines=true" >> config.txt PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features --features "abi3" - PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features --features "$(make list_all_additive_features)" - PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features --features "abi3 $(make list_all_additive_features)" + PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features --features full + PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features --features "abi3 full" done build: @@ -146,12 +146,6 @@ jobs: name: Prepare LD_LIBRARY_PATH (Ubuntu only) run: echo LD_LIBRARY_PATH=${pythonLocation}/lib >> $GITHUB_ENV - - name: Prepare workflow settings - id: settings - shell: bash - run: | - echo "::set-output name=all_additive_features::$(make list_all_additive_features)" - - if: matrix.msrv == 'MSRV' name: Prepare minimal package versions (MSRV only) run: | @@ -159,7 +153,7 @@ jobs: cargo update -p hashbrown:0.11.2 --precise 0.9.1 - name: Build docs - run: cargo doc --no-deps --no-default-features --features "${{ steps.settings.outputs.all_additive_features }}" + run: cargo doc --no-deps --no-default-features --features full - name: Build (no features) run: cargo build --lib --tests --no-default-features @@ -182,26 +176,26 @@ jobs: cargo test --no-default-features - name: Build (all additive features) - run: cargo build --lib --tests --no-default-features --features "${{ steps.settings.outputs.all_additive_features }}" + run: cargo build --lib --tests --no-default-features --features full - if: ${{ startsWith(matrix.python-version, 'pypy') }} name: Build PyPy (abi3-py37) - run: cargo build --lib --tests --no-default-features --features "abi3-py37 ${{ steps.settings.outputs.all_additive_features }}" + run: cargo build --lib --tests --no-default-features --features "abi3-py37 full" # Run tests (except on PyPy, because no embedding API). - if: ${{ !startsWith(matrix.python-version, 'pypy') }} name: Test - run: cargo test --no-default-features --features "${{ steps.settings.outputs.all_additive_features }}" + run: cargo test --no-default-features --features full # Run tests again, but in abi3 mode - if: ${{ !startsWith(matrix.python-version, 'pypy') }} name: Test (abi3) - run: cargo test --no-default-features --features "abi3 ${{ steps.settings.outputs.all_additive_features }}" + run: cargo test --no-default-features --features "abi3 full" # Run tests again, for abi3-py37 (the minimal Python version) - if: ${{ (!startsWith(matrix.python-version, 'pypy')) && (matrix.python-version != '3.7') }} name: Test (abi3-py37) - run: cargo test --no-default-features --features "abi3-py37 ${{ steps.settings.outputs.all_additive_features }}" + run: cargo test --no-default-features --features "abi3-py37 full" - name: Test proc-macro code run: cargo test --manifest-path=pyo3-macros-backend/Cargo.toml @@ -281,8 +275,8 @@ jobs: cargo llvm-cov clean --workspace cargo llvm-cov --package $ALL_PACKAGES --no-report cargo llvm-cov --package $ALL_PACKAGES --no-report --features abi3 - cargo llvm-cov --package $ALL_PACKAGES --no-report --features $(make list_all_additive_features) - cargo llvm-cov --package $ALL_PACKAGES --no-report --features abi3 $(make list_all_additive_features) + cargo llvm-cov --package $ALL_PACKAGES --no-report --features full + cargo llvm-cov --package $ALL_PACKAGES --no-report --features "abi3 full" cargo llvm-cov --package $ALL_PACKAGES --no-run --lcov --output-path coverage.lcov shell: bash env: diff --git a/.github/workflows/guide.yml b/.github/workflows/guide.yml index 923fedd1f5f..d7566672f11 100644 --- a/.github/workflows/guide.yml +++ b/.github/workflows/guide.yml @@ -35,6 +35,29 @@ jobs: TAG_NAME="${GITHUB_REF##*/}" echo "::set-output name=tag_name::${TAG_NAME}" + # Build some internal docs and inject a banner on top of it. + - name: Build the internal docs + run: | + mkdir target + mkdir -p gh-pages-build/internal + echo "
⚠️ Internal Docs ⚠️ Not Public API 👉 Official Docs Here
" > target/banner.html + cargo +nightly pyo3_doc_internal + cp -r target/doc gh-pages-build/internal + env: + RUSTDOCFLAGS: "--cfg docsrs --Z unstable-options --document-hidden-items --html-before-content target/banner.html" + + - name: Deploy internal docs + if: ${{ github.ref == 'refs/heads/main' || github.event_name == 'release' }} + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./gh-pages-build/internal + destination_dir: internal + full_commit_message: "Upload internal documentation" + + - name: Clear the extra artefacts created earlier + run: rm -rf target + # This builds the book in gh-pages-build. See https://github.com/rust-lang-nursery/mdBook/issues/698 - name: Build the guide run: mdbook build -d ../gh-pages-build guide @@ -44,11 +67,11 @@ jobs: # This adds the docs to gh-pages-build/doc - name: Build the doc run: | - cargo +nightly rustdoc --lib --no-default-features --features="macros num-bigint num-complex hashbrown indexmap serde multiple-pymethods eyre anyhow" -- --cfg docsrs + cargo +nightly pyo3_doc_scrape cp -r target/doc gh-pages-build/doc echo "" > gh-pages-build/doc/index.html - - name: Deploy + - name: Deploy docs and the guide if: ${{ github.ref == 'refs/heads/main' || github.event_name == 'release' }} uses: peaceiris/actions-gh-pages@v3 with: @@ -56,7 +79,6 @@ jobs: publish_dir: ./gh-pages-build/ destination_dir: ${{ steps.prepare_tag.outputs.tag_name }} full_commit_message: "Upload documentation for ${{ steps.prepare_tag.outputs.tag_name }}" - release: needs: build runs-on: ubuntu-latest diff --git a/Cargo.toml b/Cargo.toml index b81f1ae6ea2..7f724dd824e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -79,6 +79,10 @@ auto-initialize = [] # Optimizes PyObject to Vec conversion and so on. nightly = [] +# Activates all additional features +# This is mostly intended for testing purposes - activating *all* of these isn't particularly useful. +full = ["macros", "macros", "multiple-pymethods", "num-bigint", "num-complex", "hashbrown", "serde", "indexmap", "eyre", "anyhow"] + [[bench]] name = "bench_call" harness = false diff --git a/Contributing.md b/Contributing.md index 5c998d64b31..118ba3c94a9 100644 --- a/Contributing.md +++ b/Contributing.md @@ -9,7 +9,9 @@ If you want to become familiar with the codebase, see ## Getting started contributing -Please join in with any part of PyO3 which interests you. We use GitHub issues to record all bugs and ideas. Feel free to request an issue to be assigned to you if you want to work on it. +Please join in with any part of PyO3 which interests you. We use GitHub issues to record all bugs and ideas. Feel free to request an issue to be assigned to you if you want to work on it. + +You can browse the API of the non-public parts of PyO3 [here](https://pyo3.rs/internal/pyo3/index.html). The following sections also contain specific ideas on where to start contributing to PyO3. @@ -34,7 +36,8 @@ There are some specific areas of focus where help is currently needed for the do - Issues requesting documentation improvements are tracked with the [documentation](https://github.com/PyO3/pyo3/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation) label. - Not all APIs had docs or examples when they were made. The goal is to have documentation on all PyO3 APIs ([#306](https://github.com/PyO3/pyo3/issues/306)). If you see an API lacking a doc, please write one and open a PR! -You can build the docs (including all features) with `cargo +nightly rustdoc --features="$(make list_all_additive_features)" --open -- --cfg docsrs`. +You can build the docs (including all features) with +```cargo +nightly pyo3_doc_scrape``` #### Doctests @@ -47,7 +50,7 @@ https://doc.rust-lang.org/rustdoc/documentation-tests.html for a guide on doctes You can preview the user guide by building it locally with `mdbook`. First, [install `mdbook`](https://rust-lang.github.io/mdBook/cli/index.html). Then, run -`mdbook build -d ../gh-pages-build guide --open`. +```mdbook build -d ../gh-pages-build guide --open``` ### Help design the next PyO3 @@ -71,7 +74,7 @@ Formatting, linting and tests are checked for all Rust and Python code. In addit Tests run with all supported Python versions with the latest stable Rust compiler, as well as for Python 3.9 with the minimum supported Rust version. -If you are adding a new feature, you should add it to the `ALL_ADDITIVE_FEATURES` declaration in the `Makefile` so that it is tested in CI. +If you are adding a new feature, you should add it to the `full` feature in our *Cargo.toml** so that it is tested in CI. ## Python and Rust version support policy diff --git a/pyo3-macros-backend/src/lib.rs b/pyo3-macros-backend/src/lib.rs index 69fc24d250a..ac8cc30a746 100644 --- a/pyo3-macros-backend/src/lib.rs +++ b/pyo3-macros-backend/src/lib.rs @@ -1,7 +1,7 @@ // Copyright (c) 2017-present PyO3 Project and Contributors //! This crate contains the implementation of the proc macro attributes -#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] #![recursion_limit = "1024"] // Listed first so that macros in this module are available in the rest of the crate. diff --git a/pyo3-macros-backend/src/method.rs b/pyo3-macros-backend/src/method.rs index dda829bed3b..e7d0a00e21f 100644 --- a/pyo3-macros-backend/src/method.rs +++ b/pyo3-macros-backend/src/method.rs @@ -64,17 +64,17 @@ impl<'a> FnArg<'a> { #[derive(Clone, PartialEq, Debug, Copy, Eq)] pub enum MethodTypeAttribute { - /// #[new] + /// `#[new]` New, - /// #[classmethod] + /// `#[classmethod]` ClassMethod, - /// #[classattr] + /// `#[classattr]` ClassAttribute, - /// #[staticmethod] + /// `#[staticmethod]` StaticMethod, - /// #[getter] + /// `#[getter]` Getter, - /// #[setter] + /// `#[setter]` Setter, } diff --git a/pyo3-macros/src/lib.rs b/pyo3-macros/src/lib.rs index a6f6725c6e5..61ee90a4ef8 100644 --- a/pyo3-macros/src/lib.rs +++ b/pyo3-macros/src/lib.rs @@ -2,7 +2,7 @@ //! This crate declares only the proc macro attributes, as a crate defining proc macro attributes //! must not contain any other public items. -#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] extern crate proc_macro; use proc_macro::TokenStream; diff --git a/src/conversions/anyhow.rs b/src/conversions/anyhow.rs index e9d1e339ed7..463e1265046 100644 --- a/src/conversions/anyhow.rs +++ b/src/conversions/anyhow.rs @@ -1,6 +1,9 @@ #![cfg(feature = "anyhow")] -//! A conversion from [anyhow]’s [`Error`][anyhow_error] type to [`PyErr`]. +//! A conversion from +//! [anyhow](https://docs.rs/anyhow/ "A trait object based error system for easy idiomatic error handling in Rust applications.")’s +//! [`Error`](https://docs.rs/anyhow/latest/anyhow/struct.Error.html "Anyhows `Error` type, a wrapper around a dynamic error type") +//! type to [`PyErr`]. //! //! Use of an error handling library like [anyhow] is common in application code and when you just //! want error handling to be easy. If you are writing a library or you need more control over your @@ -101,8 +104,6 @@ //! } //! ``` //! -//! [anyhow]: https://docs.rs/anyhow/ "A trait object based error system for easy idiomatic error handling in Rust applications." -//! [anyhow_error]: https://docs.rs/anyhow/latest/anyhow/struct.Error.html "Anyhows `Error` type, a wrapper around a dynamic error type" //! [`RuntimeError`]: https://docs.python.org/3/library/exceptions.html#RuntimeError "Built-in Exceptions — Python documentation" //! [Error handling]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html "Recoverable Errors with Result - The Rust Programming Language" diff --git a/src/conversions/eyre.rs b/src/conversions/eyre.rs index 4d4014ff297..546a7fbc230 100644 --- a/src/conversions/eyre.rs +++ b/src/conversions/eyre.rs @@ -1,6 +1,8 @@ #![cfg(feature = "eyre")] -//! A conversion from [eyre]’s [`Report`] type to [`PyErr`]. +//! A conversion from +//! [eyre](https://docs.rs/eyre/ "A library for easy idiomatic error handling and reporting in Rust applications.")’s +//! [`Report`] type to [`PyErr`]. //! //! Use of an error handling library like [eyre] is common in application code and when you just //! want error handling to be easy. If you are writing a library or you need more control over your diff --git a/src/internal_tricks.rs b/src/internal_tricks.rs index 307f1bfc9e3..27add5ca80a 100644 --- a/src/internal_tricks.rs +++ b/src/internal_tricks.rs @@ -4,7 +4,8 @@ use std::marker::PhantomData; use std::rc::Rc; /// A marker type that makes the type !Send. -/// Temporal hack until https://github.com/rust-lang/rust/issues/13231 is resolved. +/// +/// Temporal hack until is resolved. pub(crate) type Unsendable = PhantomData>; pub struct PrivateMarker; From 9512ce4e879d9423372ebbb37ab2b42ad702163f Mon Sep 17 00:00:00 2001 From: mejrs Date: Wed, 22 Dec 2021 12:12:16 +0100 Subject: [PATCH 2/5] Fix call example --- examples/decorator/tests/example.py | 11 +++++++++++ guide/src/class/call.md | 2 +- 2 files changed, 12 insertions(+), 1 deletion(-) create mode 100644 examples/decorator/tests/example.py diff --git a/examples/decorator/tests/example.py b/examples/decorator/tests/example.py new file mode 100644 index 00000000000..5725a2ed024 --- /dev/null +++ b/examples/decorator/tests/example.py @@ -0,0 +1,11 @@ +@Counter +def say_hello(): + print("hello") + + +say_hello() +say_hello() +say_hello() +say_hello() + +assert say_hello.count == 4 diff --git a/guide/src/class/call.md b/guide/src/class/call.md index 6f7d1e03d7c..c9fe12179c6 100644 --- a/guide/src/class/call.md +++ b/guide/src/class/call.md @@ -21,7 +21,7 @@ An example crate containing this pyclass can be found [here](https://github.com/ Python code: ```python -{{#include ../../../examples/decorator/src/test.py}} +{{#include ../../../examples/decorator/tests/example.py}} ``` Output: From eccdcf7adbbe1694f48928e821f87c13006b503a Mon Sep 17 00:00:00 2001 From: mejrs Date: Wed, 22 Dec 2021 12:31:14 +0100 Subject: [PATCH 3/5] fix link --- Contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contributing.md b/Contributing.md index 118ba3c94a9..5835940d8d5 100644 --- a/Contributing.md +++ b/Contributing.md @@ -11,7 +11,7 @@ If you want to become familiar with the codebase, see Please join in with any part of PyO3 which interests you. We use GitHub issues to record all bugs and ideas. Feel free to request an issue to be assigned to you if you want to work on it. -You can browse the API of the non-public parts of PyO3 [here](https://pyo3.rs/internal/pyo3/index.html). +You can browse the API of the non-public parts of PyO3 [here](https://pyo3.rs/internal/doc/pyo3/index.html). The following sections also contain specific ideas on where to start contributing to PyO3. From ff202f466005dba3b63122e11ab8acf5eeb61b2b Mon Sep 17 00:00:00 2001 From: Bruno Kolenbrander <59372212+mejrs@users.noreply.github.com> Date: Fri, 24 Dec 2021 08:12:04 +0100 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: David Hewitt <1939362+davidhewitt@users.noreply.github.com> --- .github/workflows/ci.yml | 4 ++-- Cargo.toml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5ae04472c52..33d54964c13 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -64,8 +64,8 @@ jobs: echo "suppress_build_script_link_lines=true" >> config.txt PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features --features "abi3" - PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features --features full - PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --no-default-features --features "abi3 full" + PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --features full + PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --features "abi3 full" done build: diff --git a/Cargo.toml b/Cargo.toml index 7f724dd824e..992eb932a88 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -81,7 +81,7 @@ nightly = [] # Activates all additional features # This is mostly intended for testing purposes - activating *all* of these isn't particularly useful. -full = ["macros", "macros", "multiple-pymethods", "num-bigint", "num-complex", "hashbrown", "serde", "indexmap", "eyre", "anyhow"] +full = ["macros", "multiple-pymethods", "num-bigint", "num-complex", "hashbrown", "serde", "indexmap", "eyre", "anyhow"] [[bench]] name = "bench_call" From 8c2970939df8966e60b25371ae051f419d301b98 Mon Sep 17 00:00:00 2001 From: mejrs Date: Tue, 28 Dec 2021 05:38:45 +0100 Subject: [PATCH 5/5] Resolve merge conflicts --- .cargo/config | 6 ++++++ .cargo/config.toml | 7 ------- src/impl_/not_send.rs | 2 +- 3 files changed, 7 insertions(+), 8 deletions(-) delete mode 100644 .cargo/config.toml diff --git a/.cargo/config b/.cargo/config index 35049cbcb13..c6d1fd86d4a 100644 --- a/.cargo/config +++ b/.cargo/config @@ -1,2 +1,8 @@ [alias] xtask = "run --package xtask --" +pyo3_doc = "doc --lib --no-default-features --features=full --no-deps --workspace --open --exclude pyo3-macros --exclude pyo3-macros-backend" +pyo3_doc_scrape = "doc --lib --no-default-features --features=full --no-deps --workspace --open --exclude pyo3-macros --exclude pyo3-macros-backend -Z unstable-options -Z rustdoc-scrape-examples=examples" +pyo3_doc_internal = "doc --lib --no-default-features --features=full --no-deps --workspace --open --document-private-items -Z unstable-options -Z rustdoc-scrape-examples=examples" + +[build] +rustdocflags = ["--cfg", "docsrs"] diff --git a/.cargo/config.toml b/.cargo/config.toml deleted file mode 100644 index b3627e04e9a..00000000000 --- a/.cargo/config.toml +++ /dev/null @@ -1,7 +0,0 @@ -[alias] -pyo3_doc = "doc --lib --no-default-features --features=full --no-deps --workspace --open --exclude pyo3-macros --exclude pyo3-macros-backend" -pyo3_doc_scrape = "doc --lib --no-default-features --features=full --no-deps --workspace --open --exclude pyo3-macros --exclude pyo3-macros-backend -Z unstable-options -Z rustdoc-scrape-examples=examples" -pyo3_doc_internal = "doc --lib --no-default-features --features=full --no-deps --workspace --open --document-private-items -Z unstable-options -Z rustdoc-scrape-examples=examples" - -[build] -rustdocflags = ["--cfg", "docsrs"] diff --git a/src/impl_/not_send.rs b/src/impl_/not_send.rs index fca8a96cbad..97c2984aff8 100644 --- a/src/impl_/not_send.rs +++ b/src/impl_/not_send.rs @@ -3,7 +3,7 @@ use std::marker::PhantomData; use crate::Python; /// A marker type that makes the type !Send. -/// Workaround for lack of !Send on stable (https://github.com/rust-lang/rust/issues/68318). +/// Workaround for lack of !Send on stable (). pub(crate) struct NotSend(PhantomData<*mut Python<'static>>); pub(crate) const NOT_SEND: NotSend = NotSend(PhantomData);