Sphinx/ readthedocs integration guidelines

[clbarnes]

I'm going to be taking a look at this myself soon, just wanted to make sure nobody else had any tips before I got started!

For its auto-doc stuff, I believe sphinx needs to be able to import the library, which means it needs to be able to build the rust component. Readthedocs, therefore, needs to be able to compile the rust. Simplest way to do this seems to be to use the readthedocs config file to set a docker image with both rust and python (probably konstin2/maturin as a first pass) and go from there.

Readthedocs seems worth doing (rather than maintaining in-tree HTML files for gh-pages) because you can easily host multiple branches and reduce git churn.

EDIT: to clarify, this issue is to address the situation where users have a python library with sphinx/RtD documentation, then add a bit of rust to it and find RtD throws a fit.

[konstin]

I haven't tried yet and I only have sphinx experience with a pure python project, but I'd be very interested in documenting this.

[casellimarco]

Hi, are there any news on this front?

[tafia]

The best solution I've found is to convert the markdowns on sphinx conf.py (here using m2r but other modules might be better?)

# Convert markdown ...

def docstring(app, what, name, obj, options, lines):
    md  = '\n'.join(lines)
    rst = m2r.convert(md)
    lines.clear()
    lines += rst.splitlines()

def setup(app):
    app.connect('autodoc-process-docstring', docstring)

[clbarnes]

For informational purposes, then, am I right in thinking that the recommendation is to follow this repo's example? So

1. As part of CI, build docs and upload them somewhere as an artifact
2. Deploy the artifact on some host using generic hooks

[messense]

Yeah, I would recommend netlify as it has a seamless workflow with GitHub especially the deploy preview feature in PR.

FYI, Here is maturin guide's URL for now until we get a maturin.pyo3.rs subdomain: https://maturin-guide.netlify.app/

[clbarnes]

Ah, but this only builds a "dumb" mdbook, right? Rather than building the project to get introspection on docstrings and so on. Presumably the netlify environment is flexible enough that you can just install python, install all the requirements, install sphinx, install maturin and cargo, and build the project to make that work.

[messense]

Presumably the netlify environment is flexible enough that you can just install python, install all the requirements, install sphinx, install maturin and cargo, and build the project to make that work.

Yes, but there aren't many Python APIs we need to document in maturin. Only PEP 517 and PEP 660 interface implementations in https://github.com/PyO3/maturin/blob/main/maturin/__init__.py . Rust API is covered by docs.rs: https://docs.rs/maturin

[messense]

Maybe I misunderstood the main purpose of this issue. If you're talking about documenting a maturin produced Python package then we still don't have a guideline yet.

[clbarnes]

Yes I think that's it - the situation where users have a python library with sphinx/RtD documentation, then add a bit of rust to it and find RtD throws a fit. Have edited the OP.

[messense]

I think netlify environment is flexible enough, it has rustup, cargo preinstalled and Python is supported.

[messense]

Here's a netlify sphinx example I made: messense/rjieba-py#2

[messense]

I think readthedocs should also work, at least cryptography is using it: https://github.com/pyca/cryptography/blob/2c808f08079f4c7751148c2783180bdcf9c1b2dd/.readthedocs.yml

Edit: It works for me: https://github.com/messense/rjieba-py/blob/master/.readthedocs.yml

https://rjieba-py.readthedocs.io/en/latest/