ENH: Test full output and coverage

Author: larsoner

.coveragerc

@@ -0,0 +1,6 @@
+[run]
+branch = True
+source = numpydoc
+include = */numpydoc/*
+omit =
+    */setup.py

.gitignore

@@ -13,3 +13,5 @@ doc/_build
 build
 dist
 doc/_build
+numpydoc/tests/tinybuild/_build
+numpydoc/tests/tinybuild/generated

.travis.yml

@@ -15,7 +15,7 @@ cache:
 before_install:
   - sudo apt-get install texlive texlive-latex-extra latexmk
   - pip install --upgrade pip setuptools  # Upgrade pip and setuptools to get ones with `wheel` support
-  - pip install pytest pytest-cov numpy matplotlib sphinx${SPHINX_SPEC}
+  - pip install pytest pytest-cov pytest-sugar numpy matplotlib sphinx${SPHINX_SPEC} codecov
 script:
   - |
     python setup.py sdist
@@ -26,3 +26,7 @@ script:
     cd ../doc
     make SPHINXOPTS=$SPHINXOPTS html
     make SPHINXOPTS=$SPHINXOPTS latexpdf
+after_script:
+  - |
+    cd ../dist
+    codecov

codecov.yml

@@ -0,0 +1,14 @@
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 0.01
+    patch: false
+    changes: false
+comment:
+  layout: "header, diff, sunburst, uncovered"
+  behavior: default

numpydoc/tests/test_full.py

@@ -0,0 +1,60 @@
+from io import StringIO
+import os.path as op
+import shutil
+
+import pytest
+from sphinx.application import Sphinx
+from sphinx.util.docutils import docutils_namespace
+
+
+# Test framework adapted from sphinx-gallery
+@pytest.fixture(scope='module')
+def sphinx_app(tmpdir_factory):
+    temp_dir = (tmpdir_factory.getbasetemp() / 'root').strpath
+    src_dir = op.join(op.dirname(__file__), 'tinybuild')
+
+    def ignore(src, names):
+        return ('_build', 'generated')
+
+    shutil.copytree(src_dir, temp_dir, ignore=ignore)
+    # For testing iteration, you can get similar behavior just doing `make`
+    # inside the tinybuild directory
+    src_dir = temp_dir
+    conf_dir = temp_dir
+    out_dir = op.join(temp_dir, '_build', 'html')
+    toctrees_dir = op.join(temp_dir, '_build', 'toctrees')
+    # Avoid warnings about re-registration, see:
+    # https://github.com/sphinx-doc/sphinx/issues/5038
+    with docutils_namespace():
+        app = Sphinx(src_dir, conf_dir, out_dir, toctrees_dir,
+                     buildername='html', status=StringIO())
+        # need to build within the context manager
+        # for automodule and backrefs to work
+        app.build(False, [])
+    return app
+
+
+def test_class(sphinx_app):
+    """Test that class documentation is reasonable."""
+    src_dir, out_dir = sphinx_app.srcdir, sphinx_app.outdir
+    class_rst = op.join(src_dir, 'generated', 'nd_test_mod.MyClass.rst')
+    with open(class_rst, 'r') as fid:
+        rst = fid.read()
+    assert r'nd\_test\_mod.MyClass' in rst  # properly escaped
+    class_html = op.join(out_dir, 'generated', 'nd_test_mod.MyClass.html')
+    with open(class_html, 'r') as fid:
+        html = fid.read()
+    # escaped * chars should no longer be preceded by \'s
+    assert r'\*' in html  # XXX should be "not in", bug!
+    assert 'self,' in html   # XXX should be "not in", bug!
+
+
+def test_function(sphinx_app):
+    """Test that a timings page is created."""
+    out_dir = sphinx_app.outdir
+    function_html = op.join(out_dir, 'generated',
+                            'nd_test_mod.my_function.html')
+    with open(function_html, 'r') as fid:
+        html = fid.read()
+    assert r'\*args' not in html
+    assert '*args' in html

numpydoc/tests/tinybuild/Makefile

@@ -0,0 +1,11 @@
+all: clean html show
+
+clean:
+	rm -rf _build/*
+	rm -rf generated/
+
+html:
+	sphinx-build -b html -d _build/doctrees . _build/html
+
+show:
+	@python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/_build/html/index.html')"

numpydoc/tests/tinybuild/conf.py

@@ -0,0 +1,22 @@
+import os
+import sys
+path = os.path.dirname(__file__)
+if path not in sys.path:
+    sys.path.insert(0, path)
+import nd_test_mod  # noqa
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'numpydoc',
+]
+project = 'nd_test_mod'
+autosummary_generate = True
+source_suffix = '.rst'
+master_doc = 'index'
+exclude_patterns = ['_build']
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}
+nitpicky = True
+highlight_language = 'python3'
+numpydoc_xref_param_type = True

numpydoc/tests/tinybuild/index.rst

@@ -0,0 +1,4 @@
+nd_test_mod
+===========
+
+.. automodule:: nd_test_mod

numpydoc/tests/tinybuild/nd_test_mod.py

@@ -0,0 +1,51 @@
+"""Numpdoc test module.
+
+.. currentmodule:: nd_test_mod
+
+.. autosummary::
+   :toctree: generated/
+
+   MyClass
+   my_function
+"""
+
+__all__ = ['MyClass', 'my_function']
+
+
+class MyClass(object):
+    """A class.
+
+    Parameters
+    ----------
+    *args : iterable
+        Arguments.
+    **kwargs : dict
+        Keyword arguments.
+    """
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+
+def my_function(*args, **kwargs):
+    """Return None.
+
+    See [1]_.
+
+    Parameters
+    ----------
+    *args : iterable
+        Arguments.
+    **kwargs : dict
+        Keyword arguments.
+
+    Returns
+    -------
+    out : None
+        The output.
+
+    References
+    ----------
+    .. [1] https://numpydoc.readthedocs.io
+    """
+    return None

setup.cfg

@@ -3,5 +3,5 @@ addopts =
     --showlocals --doctest-modules -ra --cov-report= --cov=numpydoc
     --junit-xml=junit-results.xml --ignore=doc/conf.py
 filterwarnings =
+    ignore:'U' mode is deprecated:DeprecationWarning
     ignore:Using or importing the ABCs.*:DeprecationWarning
-