How do I use Sphinx with Cython?
cython, python-sphinx
Solution
Feel free to leave a better answer, but here is a fix that I have found.
The `dipy` project manually imports their own module from `doc/conf.py`. This requires that the module first be installed, but it fixes the import errors (and doctests will run on the Cythonized files).
However, the `error while formatting arguments` problem is still there. First you need to instruct Cython to embed the method/function signatures into the `*.so` files. Do this by setting the `embedsignature` Cython directive. The `dipy` project sets this in each `*.pyx` file, but it is also possible to set it in `setup.py` (see Cython documentation for how to do that). This still doesn't put the method signatures into the Sphinx documentation though! There is a bug report and patch for the method signatures problem here. It is still not included in the latest Sphinx release as of now (1.1.3) but if you install Sphinx from the development repo it will work.
Problem
I have recently Cythonized a project of mine by renaming all of the modules (except for the top-level `__init__.py`) to `*.pyx`, and by putting `ext_modules = [Extension('foo', ['foo.pyx'])]` in `setup.py`. Building and installing works fine. However, when I do `cd doc; make html`, Sphinx fails because it cannot import any of the modules which are now `*.pyx`. If I edit `doc/conf.py` and change `sys.path.insert(0, os.path.abspath('..'))` to `sys.path.insert(0, os.path.abspath('../build/temp.linux-x86_64-2.7'))`, then Sphinx can find all of the modules and can generate documentation, but in that case I get errors like `error while formatting arguments for foo.bar: <built-in function bar> is not a Python function`. Presumably this is because now Sphinx only has access to the `*.so` files, not the source files. That same `sys.path` modification also allows running the doctests via Sphinx (`make doctest`). The other solution I tried was using the extension `*.py` instead of `*.pyx` (and using `ext_modules = [Extension('foo', ['foo.py'])]` in `setup.py`). In this case, the documentation builds correctly, but I think the doctests now bypass Cython. I have not been able to find any information online regarding using Sphinx and Cython together. I have looked at source code for some projects which use both, but they don't seem to make use of docstrings in the `*.pyx` files. I know that Sage does, but that project is too complicated for me to pick apart. Does Sphinx support docstrings in Cython files? If so, how do I make this work?