A question about rendering python-rust api documentation

I have a crate that I am adding a Python ffi interface for, using pyo3.

A lot of Rust-only code looks like this:

pub struct Foo{
    /* fields omitted */
}

impl Foo{
    pub fn bar() -> u8{
        42
    }
}

...that I then write wrappers for:

#[pyclass(name = "Foo")]
pub struct PyFoo{
    inner: Foo
}

#[pymethods]
impl PyFoo {
    #[new]
    fn new() -> PyResult<Self> {
        Ok(Self {
            inner: Foo{/* fields */}
        })
    }
    
    fn bar(&self) -> PyResult<u8>{
        Ok(self.inner.bar())
    }
}

...so that Python code can use it like this:

foo = Foo()
bar = foo.bar()

However, I am not sure how I should document the Python api. Ideally I would want html documentation in the same style of the official Python documentation.

What I am doing now is adding doc comments and rendering documentation with rustdoc. The downside to this is that for someone only interested in the Python api there is far too much noise:

  • it will list that class as PyFoo, not Foo.
  • it's not obvious which structs, functions and methods are actually available (as opposed to rust only)
  • pyo3 itself also generates a ton of impls that are irrelevant to someone using the Python api

In a perfect world there would be a rustdoc plugin that covers this. Does something like that exist?

An alternative would be to use something like Sphinx to render python documentation - however actually using and setting up Sphinx is a disaster (especially compared to rustdoc) that I'd rather avoid.

1 Like

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.