From 0d484936e9b3e5253d363a47f8aac7d9c420db20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihai=20Capot=C4=83?= Date: Thu, 5 Oct 2017 11:55:08 -0700 Subject: [PATCH] docs: Use sphinx-gallery This PR only introduces the infrastructure and an eventseg example. The rest of the examples will need to be converted in future PRs. Note that the README files have to have the "txt" extension and the RST titles within have to be formatted hierarchically at least for the first two levels (`examples` and its subdirectories) so they are displayed properly in the resulting HTML. Fixes #268. --- .gitignore | 2 ++ docs/Makefile | 2 +- docs/conf.py | 7 +++++++ docs/index.rst | 1 + docs/newsfragments/268.doc | 1 + examples/README.txt | 3 +++ examples/eventseg/README.txt | 2 ++ .../eventseg/{simulated_data.py => plot_simulated_data.py} | 4 +++- requirements-dev.txt | 3 +++ 9 files changed, 23 insertions(+), 2 deletions(-) create mode 100644 docs/newsfragments/268.doc create mode 100644 examples/README.txt create mode 100644 examples/eventseg/README.txt rename examples/eventseg/{simulated_data.py => plot_simulated_data.py} (96%) diff --git a/.gitignore b/.gitignore index 4147ffe5d..1d78d41bd 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,8 @@ build coverage.xml dist docs/*.rst +docs/examples +docs/backreferences examples/data htmlcov .idea diff --git a/docs/Makefile b/docs/Makefile index 5bb51661b..84806808e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -53,7 +53,7 @@ help: @echo " coverage to run coverage check of the documentation (if enabled)" clean: - rm -rf $(BUILDDIR)/* + rm -rf $(BUILDDIR)/* backreferences examples html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/conf.py b/docs/conf.py index fb7f60476..43110b53e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,6 +40,7 @@ 'sphinx.ext.coverage', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', + 'sphinx_gallery.gen_gallery', ] # Add any paths that contain templates here, relative to this directory. @@ -290,3 +291,9 @@ #texinfo_no_detailmenu = False napoleon_include_special_with_doc = True + +sphinx_gallery_conf = { + 'backreferences_dir': 'backreferences', + 'examples_dirs': '../examples', + 'gallery_dirs': 'examples', +} diff --git a/docs/index.rst b/docs/index.rst index 2713a0d73..9cc83531a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,7 @@ Table of contents .. toctree:: release_notes + examples/index api contributing diff --git a/docs/newsfragments/268.doc b/docs/newsfragments/268.doc new file mode 100644 index 000000000..eb4bd5a40 --- /dev/null +++ b/docs/newsfragments/268.doc @@ -0,0 +1 @@ +Add examples to HTML documentation using Sphinx-Gallery. diff --git a/examples/README.txt b/examples/README.txt new file mode 100644 index 000000000..b90c0e1cb --- /dev/null +++ b/examples/README.txt @@ -0,0 +1,3 @@ +======== +Examples +======== diff --git a/examples/eventseg/README.txt b/examples/eventseg/README.txt new file mode 100644 index 000000000..de8bf411d --- /dev/null +++ b/examples/eventseg/README.txt @@ -0,0 +1,2 @@ +Event segmentation examples +=========================== diff --git a/examples/eventseg/simulated_data.py b/examples/eventseg/plot_simulated_data.py similarity index 96% rename from examples/eventseg/simulated_data.py rename to examples/eventseg/plot_simulated_data.py index deb090bf9..1618d20c7 100644 --- a/examples/eventseg/simulated_data.py +++ b/examples/eventseg/plot_simulated_data.py @@ -1,4 +1,6 @@ -"""Example of finding event segmentations on simulated data +""" +Example of finding event segmentations on simulated data +======================================================== This code generates simulated datasets that have temporally-clustered structure (with the same series of latent event patterns). An event diff --git a/requirements-dev.txt b/requirements-dev.txt index 2f4756dcf..3fbd03368 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,11 +1,14 @@ coverage flake8 flake8-print +matplotlib mypy numdifftools +pillow pytest restructuredtext-lint setuptools_scm sphinx +sphinx-gallery sphinx_rtd_theme towncrier