guide: add contributing page (#2442)

Co-authored-by: messense <messense@icloud.com>

.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
+          echo "<div class='internal-banner' style='position:fixed; z-index: 99999; color:red;border:3px solid red;margin-left: auto; margin-right: auto; width: 430px;left:0;right: 0;'><div style='display: flex; align-items: center; justify-content: center;'> ⚠️ Internal Docs ⚠️ Not Public API 👉 <a href='https://pyo3.rs/main/doc/pyo3/index.html' style='color:red;text-decoration:underline;'>Official Docs Here</a></div></div>" > banner.html
-          mkdir -p gh-pages-build/internal
-          echo "<div class='internal-banner' style='position:fixed; z-index: 99999; color:red;border:3px solid red;margin-left: auto; margin-right: auto; width: 430px;left:0;right: 0;'><div style='display: flex; align-items: center; justify-content: center;'> ⚠️ Internal Docs ⚠️ Not Public API 👉 <a href='https://pyo3.rs/main/doc/pyo3/index.html' style='color:red;text-decoration:underline;'>Official Docs Here</a></div></div>" > target/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
+          publish_dir: ./target/doc
-          destination_dir: internal
+          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 "<meta http-equiv=refresh content=0;url=pyo3/index.html>" > target/guide/doc/index.html
-          echo "<meta http-equiv=refresh content=0;url=pyo3/index.html>" > gh-pages-build/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 }}"
 

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
+First, install [`mdbook`][mdbook] and [`nox`][nox]. Then, run
-```mdbook build -d ../gh-pages-build guide --open```
+
+```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

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)

guide/src/contributing.md

@@ -0,0 +1 @@
+{{#include ../../Contributing.md}}

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)