From 7726bc7426d928e12a037744ad6cd2f58feb2093 Mon Sep 17 00:00:00 2001
From: Leo Singer <leo.singer@ligo.org>
Date: Fri, 9 Mar 2018 23:54:33 -0500
Subject: [PATCH] WIP: Sphinx autodoc picks up tasks automatically only if
 `undoc-members` is set (#4584)

* Add unit test for celery.contrib.sphinx

Note that this unit test reveals a bug: tasks are documented
automatically (e.g. without explicitly adding a `.. autotask::`
line) only if the `undoc-members` option is set. Try removing
'`undoc-members'` from `autodoc_default_flags` in conf.py, and
the test will fail!

* WIP: Remove undoc-members in test_sphinx
---
 MANIFEST.in                      |  2 +-
 t/unit/contrib/proj/conf.py      | 10 ++++++++++
 t/unit/contrib/proj/contents.rst |  1 +
 t/unit/contrib/proj/foo.py       | 10 ++++++++++
 t/unit/contrib/test_sphinx.py    | 19 +++++++++++++++++++
 5 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 t/unit/contrib/proj/conf.py
 create mode 100644 t/unit/contrib/proj/contents.rst
 create mode 100644 t/unit/contrib/proj/foo.py
 create mode 100644 t/unit/contrib/test_sphinx.py

diff --git a/MANIFEST.in b/MANIFEST.in
index 3374a9efe53..c884571a666 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -7,7 +7,7 @@ include TODO
 include setup.cfg
 include setup.py
 
-recursive-include t *.py
+recursive-include t *.py *.rst
 recursive-include docs *
 recursive-include extra/bash-completion *
 recursive-include extra/centos *
diff --git a/t/unit/contrib/proj/conf.py b/t/unit/contrib/proj/conf.py
new file mode 100644
index 00000000000..8a2565ada2d
--- /dev/null
+++ b/t/unit/contrib/proj/conf.py
@@ -0,0 +1,10 @@
+from __future__ import absolute_import, unicode_literals
+
+import os
+import sys
+
+extensions = ['celery.contrib.sphinx', 'sphinx.ext.autodoc']
+autodoc_default_flags = ['members']
+autosummary_generate = True
+
+sys.path.insert(0, os.path.abspath('.'))
diff --git a/t/unit/contrib/proj/contents.rst b/t/unit/contrib/proj/contents.rst
new file mode 100644
index 00000000000..817717c008d
--- /dev/null
+++ b/t/unit/contrib/proj/contents.rst
@@ -0,0 +1 @@
+.. automodule:: foo
diff --git a/t/unit/contrib/proj/foo.py b/t/unit/contrib/proj/foo.py
new file mode 100644
index 00000000000..f8172f7a408
--- /dev/null
+++ b/t/unit/contrib/proj/foo.py
@@ -0,0 +1,10 @@
+from __future__ import absolute_import, unicode_literals
+
+from celery import Celery
+
+app = Celery()
+
+
+@app.task
+def bar():
+    """This task has a docstring!"""
diff --git a/t/unit/contrib/test_sphinx.py b/t/unit/contrib/test_sphinx.py
new file mode 100644
index 00000000000..dcdb368097d
--- /dev/null
+++ b/t/unit/contrib/test_sphinx.py
@@ -0,0 +1,19 @@
+from __future__ import absolute_import, unicode_literals
+
+import pkg_resources
+import pytest
+
+try:
+    sphinx_build = pkg_resources.load_entry_point(
+        'sphinx', 'console_scripts', 'sphinx-build')
+except pkg_resources.DistributionNotFound:
+    sphinx_build = None
+
+
+@pytest.mark.skipif(sphinx_build is None, reason='Sphinx is not installed')
+def test_sphinx(tmpdir):
+    srcdir = pkg_resources.resource_filename(__name__, 'proj')
+    sphinx_build([srcdir, str(tmpdir)])
+    with open(tmpdir / 'contents.html', 'r') as f:
+        contents = f.read()
+    assert 'This task has a docstring!' in contents