Using Sphinx with C extensions

[Jason]

I have written a Python module including a submodule written in C: the
module itself is called "foo" and the C part is "foo._bar". The
structure looks like:

src/
foo/__init__.py <- contains the public stuff
foo/_bar/bar.c <- the extension

foo/__init__.py imports "_bar" to augment it, and the useful stuff is
exposed in the "foo" module. This works fine when it's built, but
obviously won't work in uncompiled form, since "_bar" doesn't exist
until it's built.

So my question is: can I use the Sphinx autodoc module with it? I've
added "src" to my sys.path (in conf.py) and have this stanza in
index.rst:

.. automodule:: foo
:members:
:undoc-members:

...but when I try to build the docs, I get:

----
/path/to/project/doc/index.rst:14: (WARNING/2) autodoc can't import/
find module 'foo', it reported error: "No module named _bar", please
check your spelling and sys.path
----

Is there any way around this?

— Jason

[Georg Brandl]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Yes: build the C extension before you build the docs.

Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)

iEYEARECAAYFAk0uqt4ACgkQN9GcIYhpnLAv4ACeMxRHxvQ+Hv11f5EfIkDgbRWU
gBgAn2FxwmgoOuikFvw+Jctk72P/CpXc
=HT4t
-----END PGP SIGNATURE-----

[Jason]

On Jan 13, 3:33 pm, Georg Brandl <ge...@python.org> wrote:
> > Is there any way around this?
>
> Yes: build the C extension before you build the docs.

I use distutils to build it all, which deposits everything in a
variably named build/lib.linux-ARCH-PYVERSION dir. I've searched the
Sphinx docs for info on distutils integration, and the distutils docs
for Sphinx integration, but with no luck.

Do you have any pointers on how I can get distutils to invoke the
Sphinx builder with the right sys.path settings every time?

Cheers,
Jason

[Georg Brandl]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Sphinx does include a "setup.py build_docs" command, but it does not
handling adding the distutils build directories to sys.path. It would
probably a good idea to do this -- would you like to work on a patch?

What I usually do is to copy the built C modules to the source path
in my "make the docs" step:

cp build/lib.*/_module.so src/package

cheers,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)

iEYEARECAAYFAk0xZQUACgkQN9GcIYhpnLDupwCfd6bvaiaIkNEqjSAHcUJ41J8R
KOgAnRL65preAFeAI6Evw1K+mCZT2sIt
=sB6c
-----END PGP SIGNATURE-----

[Jason]

On Jan 15, 5:12 pm, Georg Brandl <ge...@python.org> wrote:
> Sphinx does include a "setup.py build_docs" command

How can this be invoked? Do I need to import something extra in my
setup.py?

> but it does not
> handling adding the distutils build directories to sys.path.  It would
> probably a good idea to do this -- would you like to work on a patch?

I'll see what I can do :)

> What I usually do is to copy the built C modules to the source path
> in my "make the docs" step:

Ah, I did the opposite: compute the current build path in conf.py and
add it to sys.path.

See:

http://stackoverflow.com/questions/4687608/using-sphinx-with-a-distutils-built-c-extension

Cheers,
Jason