From cae3c870182f1151e91813c077127942b2e96d6e Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 2 Aug 2019 10:18:55 -0400 Subject: [PATCH 1/7] ENH: Test full output and coverage --- .coveragerc | 6 +++ .gitignore | 2 + .travis.yml | 6 ++- codecov.yml | 14 ++++++ numpydoc/tests/test_full.py | 60 +++++++++++++++++++++++++ numpydoc/tests/tinybuild/Makefile | 11 +++++ numpydoc/tests/tinybuild/conf.py | 22 +++++++++ numpydoc/tests/tinybuild/index.rst | 4 ++ numpydoc/tests/tinybuild/nd_test_mod.py | 51 +++++++++++++++++++++ setup.cfg | 2 +- 10 files changed, 176 insertions(+), 2 deletions(-) create mode 100644 .coveragerc create mode 100644 codecov.yml create mode 100644 numpydoc/tests/test_full.py create mode 100644 numpydoc/tests/tinybuild/Makefile create mode 100644 numpydoc/tests/tinybuild/conf.py create mode 100644 numpydoc/tests/tinybuild/index.rst create mode 100644 numpydoc/tests/tinybuild/nd_test_mod.py diff --git a/.coveragerc b/.coveragerc new file mode 100644 index 00000000..92a2a252 --- /dev/null +++ b/.coveragerc @@ -0,0 +1,6 @@ +[run] +branch = True +source = numpydoc +include = */numpydoc/* +omit = + */setup.py diff --git a/.gitignore b/.gitignore index f5a885ab..1de316e2 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,5 @@ doc/_build build dist doc/_build +numpydoc/tests/tinybuild/_build +numpydoc/tests/tinybuild/generated diff --git a/.travis.yml b/.travis.yml index 69cb9d77..86fd9352 100644 --- a/.travis.yml +++ b/.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 diff --git a/codecov.yml b/codecov.yml new file mode 100644 index 00000000..1e7b888a --- /dev/null +++ b/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 diff --git a/numpydoc/tests/test_full.py b/numpydoc/tests/test_full.py new file mode 100644 index 00000000..f9e89a38 --- /dev/null +++ b/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 diff --git a/numpydoc/tests/tinybuild/Makefile b/numpydoc/tests/tinybuild/Makefile new file mode 100644 index 00000000..27af0eb3 --- /dev/null +++ b/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')" diff --git a/numpydoc/tests/tinybuild/conf.py b/numpydoc/tests/tinybuild/conf.py new file mode 100644 index 00000000..6a3a867b --- /dev/null +++ b/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 diff --git a/numpydoc/tests/tinybuild/index.rst b/numpydoc/tests/tinybuild/index.rst new file mode 100644 index 00000000..494a1278 --- /dev/null +++ b/numpydoc/tests/tinybuild/index.rst @@ -0,0 +1,4 @@ +nd_test_mod +=========== + +.. automodule:: nd_test_mod diff --git a/numpydoc/tests/tinybuild/nd_test_mod.py b/numpydoc/tests/tinybuild/nd_test_mod.py new file mode 100644 index 00000000..68a35160 --- /dev/null +++ b/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 diff --git a/setup.cfg b/setup.cfg index 1832c275..5221732a 100644 --- a/setup.cfg +++ b/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 - From d1c8f0a4e2234909ca67236a9fcb7ffc09bc2a3e Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 2 Aug 2019 10:31:27 -0400 Subject: [PATCH 2/7] FIX: Add new files to setup.py --- .gitignore | 1 + setup.py | 9 +++++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 1de316e2..26f7400b 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ dist doc/_build numpydoc/tests/tinybuild/_build numpydoc/tests/tinybuild/generated +MANIFEST diff --git a/setup.py b/setup.py index 4440a50c..87076c75 100644 --- a/setup.py +++ b/setup.py @@ -48,7 +48,12 @@ def read(fname): url="https://numpydoc.readthedocs.io", license="BSD", install_requires=["sphinx >= 1.6.5", 'Jinja2>=2.3'], - package_data={'numpydoc': ['tests/test_*.py', 'templates/*.rst']}, - test_suite = 'nose.collector', + package_data={'numpydoc': [ + 'tests/test_*.py', + 'tests/tinybuild/Makefile', + 'tests/tinybuild/index.rst', + 'tests/tinybuild/*.py', + 'templates/*.rst', + ]}, cmdclass={"sdist": sdist}, ) From 874933b7b437bd1d2e2a931ae9e7c157b8e478b4 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 2 Aug 2019 10:40:59 -0400 Subject: [PATCH 3/7] ENH: dvipng --- .travis.yml | 4 ++++ numpydoc/tests/test_full.py | 3 +-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index 86fd9352..7c561996 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,6 +3,10 @@ language: python dist: xenial sudo: false +addons: + apt: + packages: + - dvipng matrix: include: - python: 3.7 diff --git a/numpydoc/tests/test_full.py b/numpydoc/tests/test_full.py index f9e89a38..8459839b 100644 --- a/numpydoc/tests/test_full.py +++ b/numpydoc/tests/test_full.py @@ -1,4 +1,3 @@ -from io import StringIO import os.path as op import shutil @@ -27,7 +26,7 @@ def ignore(src, names): # 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()) + buildername='html') # need to build within the context manager # for automodule and backrefs to work app.build(False, []) From 77fb2c209de94eea14d5b6e0963d43768befd900 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 2 Aug 2019 10:47:30 -0400 Subject: [PATCH 4/7] FIX: Cleaner test --- .travis.yml | 10 ++++++---- numpydoc/tests/test_full.py | 4 ++++ 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/.travis.yml b/.travis.yml index 7c561996..10c38260 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,6 +7,9 @@ addons: apt: packages: - dvipng + - texlive + - texlive-latex-extra + - latexmk matrix: include: - python: 3.7 @@ -16,16 +19,15 @@ matrix: cache: directories: - $HOME/.cache/pip -before_install: - - sudo apt-get install texlive texlive-latex-extra latexmk +install: - pip install --upgrade pip setuptools # Upgrade pip and setuptools to get ones with `wheel` support - - pip install pytest pytest-cov pytest-sugar numpy matplotlib sphinx${SPHINX_SPEC} codecov + - pip install pytest pytest-cov numpy matplotlib sphinx${SPHINX_SPEC} codecov script: - | python setup.py sdist cd dist pip install numpydoc* -v - - pytest --pyargs numpydoc + - pytest -v --pyargs numpydoc - | cd ../doc make SPHINXOPTS=$SPHINXOPTS html diff --git a/numpydoc/tests/test_full.py b/numpydoc/tests/test_full.py index 8459839b..70b5657a 100644 --- a/numpydoc/tests/test_full.py +++ b/numpydoc/tests/test_full.py @@ -46,6 +46,8 @@ def test_class(sphinx_app): # 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! + # check xref + assert 'stdtypes.html#dict' in html def test_function(sphinx_app): @@ -57,3 +59,5 @@ def test_function(sphinx_app): html = fid.read() assert r'\*args' not in html assert '*args' in html + # check xref + assert 'glossary.html#term-iterable' in html From 3cf3eba4e6ba0135c6a8f9ee348b57e1550ae3b7 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 2 Aug 2019 10:50:21 -0400 Subject: [PATCH 5/7] ENH: Update --- .travis.yml | 10 ++-------- numpydoc/tests/test_full.py | 3 ++- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/.travis.yml b/.travis.yml index 10c38260..5a733caf 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,13 +3,6 @@ language: python dist: xenial sudo: false -addons: - apt: - packages: - - dvipng - - texlive - - texlive-latex-extra - - latexmk matrix: include: - python: 3.7 @@ -19,7 +12,8 @@ matrix: cache: directories: - $HOME/.cache/pip -install: +before_install: + - sudo apt-get install texlive texlive-latex-extra latexmk dvipng - 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} codecov script: diff --git a/numpydoc/tests/test_full.py b/numpydoc/tests/test_full.py index 70b5657a..33b4f6a7 100644 --- a/numpydoc/tests/test_full.py +++ b/numpydoc/tests/test_full.py @@ -1,3 +1,4 @@ +from io import StringIO import os.path as op import shutil @@ -26,7 +27,7 @@ def ignore(src, names): # https://github.com/sphinx-doc/sphinx/issues/5038 with docutils_namespace(): app = Sphinx(src_dir, conf_dir, out_dir, toctrees_dir, - buildername='html') + buildername='html', status=StringIO(u'')) # need to build within the context manager # for automodule and backrefs to work app.build(False, []) From 3875a7e1db7264014b7f39298538137e58346261 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 2 Aug 2019 10:55:58 -0400 Subject: [PATCH 6/7] BUG: Remove StringIO --- numpydoc/tests/test_full.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/numpydoc/tests/test_full.py b/numpydoc/tests/test_full.py index 33b4f6a7..0ee05c67 100644 --- a/numpydoc/tests/test_full.py +++ b/numpydoc/tests/test_full.py @@ -1,4 +1,3 @@ -from io import StringIO import os.path as op import shutil @@ -27,7 +26,7 @@ def ignore(src, names): # 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(u'')) + buildername='html') # need to build within the context manager # for automodule and backrefs to work app.build(False, []) @@ -40,7 +39,7 @@ def test_class(sphinx_app): 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 + assert r'nd\_test\_mod' 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() From 971a5a84e8463784ad879fed10f87d9d378fcc16 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Thu, 8 Aug 2019 17:25:16 -0400 Subject: [PATCH 7/7] STY: Better naming and explanations --- numpydoc/tests/test_full.py | 24 +++++++++++-------- numpydoc/tests/tinybuild/conf.py | 4 ++-- numpydoc/tests/tinybuild/index.rst | 6 ++--- ...nd_test_mod.py => numpydoc_test_module.py} | 4 ++-- 4 files changed, 21 insertions(+), 17 deletions(-) rename numpydoc/tests/tinybuild/{nd_test_mod.py => numpydoc_test_module.py} (91%) diff --git a/numpydoc/tests/test_full.py b/numpydoc/tests/test_full.py index 0ee05c67..788853dd 100644 --- a/numpydoc/tests/test_full.py +++ b/numpydoc/tests/test_full.py @@ -6,7 +6,7 @@ from sphinx.util.docutils import docutils_namespace -# Test framework adapted from sphinx-gallery +# Test framework adapted from sphinx-gallery (BSD 3-clause) @pytest.fixture(scope='module') def sphinx_app(tmpdir_factory): temp_dir = (tmpdir_factory.getbasetemp() / 'root').strpath @@ -33,31 +33,35 @@ def ignore(src, names): return app -def test_class(sphinx_app): +def test_MyClass(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') + class_rst = op.join(src_dir, 'generated', + 'numpydoc_test_module.MyClass.rst') with open(class_rst, 'r') as fid: rst = fid.read() - assert r'nd\_test\_mod' in rst # properly escaped - class_html = op.join(out_dir, 'generated', 'nd_test_mod.MyClass.html') + assert r'numpydoc\_test\_module' in rst # properly escaped + class_html = op.join(out_dir, 'generated', + 'numpydoc_test_module.MyClass.html') with open(class_html, 'r') as fid: html = fid.read() - # escaped * chars should no longer be preceded by \'s + # escaped * chars should no longer be preceded by \'s, + # if we see a \* in the output we know it's incorrect: assert r'\*' in html # XXX should be "not in", bug! + # "self" should not be in the parameter list for the class: assert 'self,' in html # XXX should be "not in", bug! - # check xref + # check xref was embedded properly (dict should link using xref): assert 'stdtypes.html#dict' in html -def test_function(sphinx_app): +def test_my_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') + 'numpydoc_test_module.my_function.html') with open(function_html, 'r') as fid: html = fid.read() assert r'\*args' not in html assert '*args' in html - # check xref + # check xref (iterable should link using xref): assert 'glossary.html#term-iterable' in html diff --git a/numpydoc/tests/tinybuild/conf.py b/numpydoc/tests/tinybuild/conf.py index 6a3a867b..71ef6640 100644 --- a/numpydoc/tests/tinybuild/conf.py +++ b/numpydoc/tests/tinybuild/conf.py @@ -3,13 +3,13 @@ path = os.path.dirname(__file__) if path not in sys.path: sys.path.insert(0, path) -import nd_test_mod # noqa +import numpydoc_test_module # noqa extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'numpydoc', ] -project = 'nd_test_mod' +project = 'numpydoc_test_module' autosummary_generate = True source_suffix = '.rst' master_doc = 'index' diff --git a/numpydoc/tests/tinybuild/index.rst b/numpydoc/tests/tinybuild/index.rst index 494a1278..a078ff88 100644 --- a/numpydoc/tests/tinybuild/index.rst +++ b/numpydoc/tests/tinybuild/index.rst @@ -1,4 +1,4 @@ -nd_test_mod -=========== +numpydoc_test_module +==================== -.. automodule:: nd_test_mod +.. automodule:: numpydoc_test_module diff --git a/numpydoc/tests/tinybuild/nd_test_mod.py b/numpydoc/tests/tinybuild/numpydoc_test_module.py similarity index 91% rename from numpydoc/tests/tinybuild/nd_test_mod.py rename to numpydoc/tests/tinybuild/numpydoc_test_module.py index 68a35160..85d990ca 100644 --- a/numpydoc/tests/tinybuild/nd_test_mod.py +++ b/numpydoc/tests/tinybuild/numpydoc_test_module.py @@ -1,6 +1,6 @@ -"""Numpdoc test module. +"""Numpydoc test module. -.. currentmodule:: nd_test_mod +.. currentmodule:: numpydoc_test_module .. autosummary:: :toctree: generated/