From 00ea4bcccee893e17deff836b39a5af38e9bc3a0 Mon Sep 17 00:00:00 2001
From: David Hewitt <1939362+davidhewitt@users.noreply.github.com>
Date: Fri, 1 Oct 2021 08:18:38 +0100
Subject: [PATCH] examples: export __doc__ in example projects

---
 examples/maturin-starter/maturin_starter/__init__.py  |  4 ++++
 examples/maturin-starter/src/lib.rs                   |  1 +
 .../maturin-starter/tests/test_maturin_starter.py     | 10 +++++++++-
 .../setuptools_rust_starter/__init__.py               |  4 ++++
 examples/setuptools-rust-starter/src/lib.rs           |  1 +
 .../tests/test_setuptools_rust_starter.py             | 11 ++++++++++-
 6 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/examples/maturin-starter/maturin_starter/__init__.py b/examples/maturin-starter/maturin_starter/__init__.py
index 44ed5e11..5fe00cb5 100644
--- a/examples/maturin-starter/maturin_starter/__init__.py
+++ b/examples/maturin-starter/maturin_starter/__init__.py
@@ -1,5 +1,9 @@
 # import the contents of the Rust library into the Python extension
+# optional: include the documentation from the Rust module
 from .maturin_starter import *
+from .maturin_starter import __all__, __doc__
+
+__all__ = __all__ + ["PythonClass"]
 
 
 class PythonClass:
diff --git a/examples/maturin-starter/src/lib.rs b/examples/maturin-starter/src/lib.rs
index 164a9b8a..3a79ca51 100644
--- a/examples/maturin-starter/src/lib.rs
+++ b/examples/maturin-starter/src/lib.rs
@@ -19,6 +19,7 @@ impl ExampleClass {
     }
 }
 
+/// An example module implemented in Rust using PyO3.
 #[pymodule]
 fn maturin_starter(py: Python, m: &PyModule) -> PyResult<()> {
     m.add_class::<ExampleClass>()?;
diff --git a/examples/maturin-starter/tests/test_maturin_starter.py b/examples/maturin-starter/tests/test_maturin_starter.py
index 961d2d54..1f3e8d9f 100644
--- a/examples/maturin-starter/tests/test_maturin_starter.py
+++ b/examples/maturin-starter/tests/test_maturin_starter.py
@@ -1,4 +1,4 @@
-from maturin_starter import PythonClass, ExampleClass
+from maturin_starter import ExampleClass, PythonClass
 
 
 def test_python_class() -> None:
@@ -9,3 +9,11 @@ def test_python_class() -> None:
 def test_example_class() -> None:
     example = ExampleClass(value=11)
     assert example.value == 11
+
+
+def test_doc() -> None:
+    import maturin_starter
+
+    assert (
+        maturin_starter.__doc__ == "An example module implemented in Rust using PyO3."
+    )
diff --git a/examples/setuptools-rust-starter/setuptools_rust_starter/__init__.py b/examples/setuptools-rust-starter/setuptools_rust_starter/__init__.py
index 074483e5..1dcb91e0 100644
--- a/examples/setuptools-rust-starter/setuptools_rust_starter/__init__.py
+++ b/examples/setuptools-rust-starter/setuptools_rust_starter/__init__.py
@@ -1,5 +1,9 @@
 # import the contents of the Rust library into the Python extension
+# optional: include the documentation from the Rust module
 from ._setuptools_rust_starter import *
+from ._setuptools_rust_starter import __all__, __doc__
+
+__all__ = __all__ + ["PythonClass"]
 
 
 class PythonClass:
diff --git a/examples/setuptools-rust-starter/src/lib.rs b/examples/setuptools-rust-starter/src/lib.rs
index 0f28e6ee..6f09f43a 100644
--- a/examples/setuptools-rust-starter/src/lib.rs
+++ b/examples/setuptools-rust-starter/src/lib.rs
@@ -19,6 +19,7 @@ impl ExampleClass {
     }
 }
 
+/// An example module implemented in Rust using PyO3.
 #[pymodule]
 fn _setuptools_rust_starter(py: Python, m: &PyModule) -> PyResult<()> {
     m.add_class::<ExampleClass>()?;
diff --git a/examples/setuptools-rust-starter/tests/test_setuptools_rust_starter.py b/examples/setuptools-rust-starter/tests/test_setuptools_rust_starter.py
index 7ca33bba..07ca6c5e 100644
--- a/examples/setuptools-rust-starter/tests/test_setuptools_rust_starter.py
+++ b/examples/setuptools-rust-starter/tests/test_setuptools_rust_starter.py
@@ -1,4 +1,4 @@
-from setuptools_rust_starter import PythonClass, ExampleClass
+from setuptools_rust_starter import ExampleClass, PythonClass
 
 
 def test_python_class() -> None:
@@ -9,3 +9,12 @@ def test_python_class() -> None:
 def test_example_class() -> None:
     example = ExampleClass(value=11)
     assert example.value == 11
+
+
+def test_doc() -> None:
+    import setuptools_rust_starter
+
+    assert (
+        setuptools_rust_starter.__doc__
+        == "An example module implemented in Rust using PyO3."
+    )