diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index f691f731..fcb47296 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -42,45 +42,45 @@ jobs: # 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 + echo "
⚠️ Internal Docs ⚠️ Not Public API 👉 Official Docs Here
" > banner.html cargo xtask 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" + RUSTDOCFLAGS: "--cfg docsrs --Z unstable-options --document-hidden-items --html-before-content 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 + publish_dir: ./target/doc + destination_dir: internal/doc 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 + # This builds the book in target/guide. - name: Build the guide - run: mdbook build -d ../gh-pages-build guide + run: | + pip install nox + nox -s build-guide env: PYO3_VERSION_TAG: ${{ steps.prepare_tag.outputs.tag_name }} - # This adds the docs to gh-pages-build/doc + # This adds the docs to target/guide/doc - name: Build the doc run: | cargo xtask doc - cp -r target/doc gh-pages-build/doc - echo "" > gh-pages-build/doc/index.html + echo "" > target/guide/doc/index.html + env: + CARGO_TARGET_DIR: target/guide - name: Deploy docs and the guide 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/ + publish_dir: ./target/guide/ destination_dir: ${{ steps.prepare_tag.outputs.tag_name }} full_commit_message: "Upload documentation for ${{ steps.prepare_tag.outputs.tag_name }}" diff --git a/Contributing.md b/Contributing.md index 07bdd7d6..2af170ca 100644 --- a/Contributing.md +++ b/Contributing.md @@ -1,6 +1,6 @@ # Contributing -Thank you for your interest in contributing to PyO3! All are welcome - please consider reading our [Code of Conduct](Code-of-Conduct.md) to keep our community positive and inclusive. +Thank you for your interest in contributing to PyO3! All are welcome - please consider reading our [Code of Conduct](https://github.com/PyO3/pyo3/blob/main/Code-of-Conduct.md) to keep our community positive and inclusive. If you are searching for ideas how to contribute, proceed to the ["Getting started contributing"](#getting-started-contributing) section. If you have found a specific issue to contribute to and need information about the development process, you may find the section ["Writing pull requests"](#writing-pull-requests) helpful. @@ -21,6 +21,7 @@ To work and develop PyO3, you need Python & Rust installed on your system. * We encourage the use of [rustup](https://rustup.rs/) to be able to select and choose specific toolchains based on the project. * [Pyenv](https://github.com/pyenv/pyenv) is also highly recommended for being able to choose a specific Python version. * [virtualenv](https://virtualenv.pypa.io/en/latest/) can also be used with or without Pyenv to use specific installed Python versions. +* [`nox`][nox] is used to automate many of our CI tasks. ### Caveats @@ -48,7 +49,10 @@ There are some specific areas of focus where help is currently needed for the do - 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 xtask doc --open``` + +```shell +cargo xtask doc --open +``` #### Doctests @@ -60,8 +64,11 @@ 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``` +First, install [`mdbook`][mdbook] and [`nox`][nox]. Then, run + +```shell +nox -s build-guide -- --open +``` ### Help design the next PyO3 @@ -129,3 +136,6 @@ In the meanwhile, some of our maintainers have personal GitHub sponsorship pages - [davidhewitt](https://github.com/sponsors/davidhewitt) - [messense](https://github.com/sponsors/messense) + +[mdbook]: https://rust-lang.github.io/mdBook/cli/index.html +[nox]: https://github.com/theacodes/nox diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index c1ed4711..ae490792 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -36,3 +36,7 @@ [Appendix C: Trait bounds](trait_bounds.md) [Appendix D: Python typing hints](python_typing_hints.md) [CHANGELOG](changelog.md) + +--- + +[Contributing](contributing.md) diff --git a/guide/src/contributing.md b/guide/src/contributing.md new file mode 100644 index 00000000..aa08bca8 --- /dev/null +++ b/guide/src/contributing.md @@ -0,0 +1 @@ +{{#include ../../Contributing.md}} diff --git a/noxfile.py b/noxfile.py index e1b918f8..ba81e1a0 100644 --- a/noxfile.py +++ b/noxfile.py @@ -194,3 +194,8 @@ def test_emscripten(session: nox.Session): session.run( "bash", "-c", f"source {info.builddir/'emsdk/emsdk_env.sh'} && cargo test" ) + + +@nox.session(name="build-guide", venv_backend="none") +def build_guide(session: nox.Session): + session.run("mdbook", "build", "-d", "../target/guide", "guide", *session.posargs)