[RFC] test: build python docs

[RFC] test: build python docs

[David Bremner]

The idea is to consider any warning from sphinx-build as a test
failure. This requires the -W option, which we probably don't want for
builds.
---

I'm not sure the best way to do this. An alternative approach would be
to build the python docs during the main build (much as we currently
build the ruby bindings). I suspect we'd want some way to disable the
"-W" option to sphinx-build in that case, so that python doc failures
don't break the entire build. On the other hand, for distros breaking
the test suite is pretty much equivalent to breaking the build. In the
proposed patch the test could be disabled by dropping sphinx-build
from the test env (which makes the man pages go away), or by patching
the single test out.


test/T390-python.sh | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/test/T390-python.sh b/test/T390-python.sh
index 312d61e8..63232677 100755
--- a/test/T390-python.sh
+++ b/test/T390-python.sh
@@ -155,4 +155,7 @@ print(list(v) == [])
 EOF
 test_expect_equal "$(cat OUTPUT)" "True"
 
+test_begin_subtest "build python docs"
+test_declare_external_prereq sphinx-build
+test_expect_success "sphinx-build -n -W \"$NOTMUCH_SRCDIR\"/bindings/python/docs/source html"
 test_done
-- 
2.15.1

Re: [RFC] test: build python docs

[David Bremner]

David Bremner <david@tethera.net> writes:

> The idea is to consider any warning from sphinx-build as a test
> failure. This requires the -W option, which we probably don't want for
> builds.
> ---
>
> I'm not sure the best way to do this. An alternative approach would be
> to build the python docs during the main build (much as we currently
> build the ruby bindings). I suspect we'd want some way to disable the
> "-W" option to sphinx-build in that case, so that python doc failures
> don't break the entire build. On the other hand, for distros breaking
> the test suite is pretty much equivalent to breaking the build. In the
> proposed patch the test could be disabled by dropping sphinx-build
> from the test env (which makes the man pages go away), or by patching
> the single test out.

Sure enough, no sooner do I send this and fix the warning about
get_config_list, I get others that I don't see an obvious fix for:

/home/bremner/software/upstream/notmuch/bindings/python/docs/source/status_and_errors.rst:17: WARNING: error while formatting arguments for notmuch.STATUS: 'Status' object has no attribute '__bases__'
/home/bremner/software/upstream/notmuch/bindings/python/docs/source/threads.rst:14: WARNING: don't know which module to import for autodocumenting u'__str__' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)