search

seanfisk / python-project-template

A template Python project with a focus on best practices.
Other
543 stars 168 forks source link

Make tox Sphinx warnings into errors. #14

Closed seanfisk closed 11 years ago

seanfisk commented 11 years ago

This will allow us to be more strict in making sure the docs build successfully. This can be done with the -W flag to sphinx-build, but we'll probably have to override paver.doctools.html() to do it.

bitmensch commented 11 years ago

I had a look at this today. I noticed the following things:

We do currently have two entry points for building sphinx html documentation, paver html which calls paver.doctools.html() behind the scenes, and the sphinx generated make html. As at a first glance paver supports only html documentation generation there's a need to keep the Makefiles around as these enable a developer to generate other kinds of documentation. Adding the -W flag in paver.doctools.html() seems to be difficult unless we would like to copy and maintain another 40 - 50 lines of code which seems to be to much for just adding another flag.

A more lightweight approach would be to add the -W flag to the SPHINXOPTS variable in Makefile and basically call make html from paver html task. Thus we would use a single entry point. Or did I miss some advantage of paver.doctools.html() over just calling make html?

@seanfisk If you agree to the suggested solution then I could come up with a PR for this.

seanfisk commented 11 years ago

We do currently have two entry points for building sphinx html documentation

Agreed, and this is sub-optimal.

Adding the -W flag in paver.doctools.html() seems to be difficult

That is what I found too. Basically we'd have to hack paver apart or maintain a separate function like you said.

Or did I miss some advantage of paver.doctools.html() over just calling make html?

The advantage is portability. One thing that I really like about paver is that everything is pure Python, so if you have Python installed correctly, everything works. Depending on the Makefile requires extra tools. Although that requirement was present before, it would now become a central requirement. It's similar to the reason I opened #15: keep it all in Python.

We would have to do a platform check to run make.bat on Windows, but I don't think that's a big deal. We can use the platform check code that's already present in the function behind paver doc_open. Of course, this makes some assumptions (e.g., make is installed on all UNIX-like platforms), but it should "just work" for most users.

On the whole, I like the idea of a single entry point and would welcome a pull request on this issue. Thanks, Ben!

seanfisk commented 11 years ago

Closed by #17.