I'm inclined to merge this, but could you add build automation so I can see travis is happy with the docs and will build them? If you'd strongly prefer to put that in a separate PR I will merge.

@glyph I'm going to push some commits so I'm sure the Travis configuration is OK, I'll let you know when I think it's ready to merge.

@glyph I added a requirements into the doc extra requirements list and changed the Travis configuration accordingly, and he seems to be happy with that.

It's not as nice as I want it to be though, AFAIK pip doesn't know how to handle installing these extras from a file or from . in non-editable mode.

There are other possibilities to install Sphinx though:

• install it once and for all at the beginning of Travis' install phase, but then we'll miss the fact that it's a dependency required to build the doc (we actually already miss it except in the inplace mode)
• add a requirements.txt file which is then installed by pip at the beginning of Travis. It's more or less the same as before except that the dependency is encoded outside of Travis, it might be better. But it means there are still 2 places to lookup for dependencies (the setup.py and the requirements.txt)

Maybe you have another suggestion?

Sphinx is not a dependency of Nevow; at no point does Nevow need to import it. So I am not worried that we would potentially be encoding dependency information in multiple places.

Accordingly, I think that we should not actually install Sphinx into the test environments; if Nevow did start importing Sphinx, that would be a bug :).

However, for a first cut I think this is good enough. Lore has already gone away, so we need to move quickly to adapt to the changing environment in which Nevow exists.

I'm going to create a couple of issues and assign them to you.