Documenting Python Extensions Made with Rust and PyO3

Python is a popular programming language, but sometimes developers need to write native extensions to optimize their code. Rust is a language that is gaining popularity among developers for writing such extensions due to its performance and memory safety. PyO3 is a tool that allows developers to write optimized, GIL-free, memory-safe Python extensions in Rust. In this article, we will discuss how to document Python extensions made with Rust and PyO3.

Ivan Kud, a developer who uses PyO3 extensively in his software, faced the challenge of documenting the extensions to help users observe only those parts that are available in Python without looking at the Rust source code. He initially wrote a markdown file with API, but this approach was not suitable for large APIs.

To solve this problem, Ivan used Rustdoc, a tool that generates documentation for Rust code. Rustdoc generates documentation in HTML format, which can be easily viewed in a web browser. Ivan used Rustdoc to generate documentation for his Python extensions made with Rust and PyO3. He added doc comments to the Rust code, which Rustdoc used to generate documentation.

Rustdoc allows developers to write documentation in Markdown format. Rustdoc also supports adding examples to the documentation. Examples can be written in Rust or Python, which makes it easy for developers to understand how to use the extensions.

Here is an example of how to use Rustdoc to generate documentation for a Python extension made with Rust and PyO3:

//! A Python module implemented in Rust.
//!
//! This module provides a function `add` that adds two numbers.
//!
//! # Examples
//!
//! ```python
//! >>> import my_module
//! >>> my_module.add(2, 3)
//! 5
//! ```

use pyo3::prelude::*;

#[pyfunction]
fn add(a: i64, b: i64) -> PyResult<i64> {
    Ok(a + b)
}

#[pymodule]
fn my_module(_py: Python, m: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(add, m)?)?;
    Ok(())
}

In the above example, the //! syntax is used to add doc comments to the Rust code. The # Examples section shows how to use the add function in Python. Rustdoc will generate documentation in HTML format, which can be easily viewed in a web browser.

In conclusion, documenting Python extensions made with Rust and PyO3 is essential for developers to understand how to use the extensions. Rustdoc is a tool that can be used to generate documentation for Rust code. Rustdoc supports Markdown format and examples, which makes it easy for developers to understand how to use the extensions. With Rust and PyO3, developers can write optimized, GIL-free, memory-safe Python extensions that can improve the performance of their code.