-
-
Notifications
You must be signed in to change notification settings - Fork 269
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Sphinx/ readthedocs integration guidelines #371
Comments
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. |
Hi, are there any news on this front? |
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) |
For informational purposes, then, am I right in thinking that the recommendation is to follow this repo's example? So
|
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 |
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. |
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 |
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. |
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. |
I think netlify environment is flexible enough, it has rustup, cargo preinstalled and Python is supported. |
Here's a netlify sphinx example I made: messense/rjieba-py#2 |
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 |
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.
The text was updated successfully, but these errors were encountered: