"Import Rust as a submodule of your project" docs are incomplete

[astrojuanlu]

Bug Description

The docs https://www.maturin.rs/project_layout#import-rust-as-a-submodule-of-your-project tell the user to change module-name, but actually that causes a warning and then an error:

⚠️  Warning: Couldn't find the symbol `PyInit__guessing_game` in the native library. Python will fail to import this module. If you're using pyo3, check that `#[pymodule]` uses `_guessing_game` as module name

Changing to fn _guessing_game or adding #[pyo3(name = "_guessing_game")] fixes the issue.

I see past references to this in #256 and PyO3/pyo3#2170 but it still seems to me that the maturin docs are not complete. Maybe I'm missing something?

Your maturin version (maturin --version)

1.8.1

Your Python version (python -V)

3.13.0

Your pip version (pip -V)

N/A

What bindings you're using

pyo3

Does cargo build work?

• Yes, it works

If on windows, have you checked that you aren't accidentally using unix path (those with the forward slash /)?

• Yes

Steps to Reproduce

Everything works:

bash-5.2$ uvx maturin new -b pyo3 --src guessing-game && cd guessing-game
  ✨ Done! New project created guessing-game
bash-5.2$ uv run python -c "from guessing_game import sum_as_string as s; print(s(2, 3))"
Using CPython 3.13.0
Creating virtual environment at: .venv
   Built guessing-game @ file:///private/tmp/guessing-game
Installed 1 package in 6ms
5

Rearrange everything with the alternate Python source directory, and check that everything still works:

bash-5.2$ mkdir rust
bash-5.2$ mv Cargo* rust
bash-5.2$ mv src rust
bash-5.2$ rm -r target
bash-5.2$ mkdir -p src/guessing_game
bash-5.2$ cat <<EOF > src/guessing_game/__init__.py
from .guessing_game import *

__doc__ = guessing_game.__doc__
if hasattr(guessing_game, "__all__"):
    __all__ = guessing_game.__all__
EOF
bash-5.2$ cat <<EOF >> pyproject.toml
[tool.uv]
# Rebuild package when any Rust files change
cache-keys = [{file = "pyproject.toml"}, {file = "rust/Cargo.toml"}, {file = "rust/**/*.rs"}]
EOF
bash-5.2$ tree -L3
.
├── pyproject.toml
├── rust
│   ├── Cargo.lock
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
├── src
│   └── guessing_game
│       └── __init__.py
└── uv.lock
bash-5.2$ uv run python -c "from guessing_game import sum_as_string as s; print(s(2, 3))"
   Built guessing-game @ file:///private/tmp/guessing-game
Uninstalled 1 package in 3ms
Installed 1 package in 8ms
5

Now, follow https://www.maturin.rs/project_layout#import-rust-as-a-submodule-of-your-project

bash-5.2$ vim pyproject.toml 
bash-5.2$ grep -A2 'tool.maturin' pyproject.toml 
[tool.maturin]
features = ["pyo3/extension-module"]
module-name = "guessing_game._guessing_game"
bash-5.2$ rm src/guessing_game/*.so

Spot the warning:

bash-5.2$ maturin build
🍹 Building a mixed python/rust project
...
⚠️  Warning: Couldn't find the symbol `PyInit__guessing_game` in the native library. Python will fail to import this module. If you're using pyo3, check that `#[pymodule]` uses `_guessing_game` as module name

Add the missing bit, and now everything works again:

bash-5.2$ vim src/lib.rs 
bash-5.2$ grep -A2 pymodule src/lib.rs 
#[pymodule]
#[pyo3(name = "_guessing_game")]
fn guessing_game(m: &Bound<'_, PyModule>) -> PyResult<()> {
bash-5.2$ uv run python -c "from guessing_game import sum_as_string as s; print(s(2, 3))"
   Built guessing-game @ file:///private/tmp/guessing-game
Uninstalled 1 package in 3ms
Installed 1 package in 11ms
5