allow building single example / example directory about sphinx-gallery HOT 19 CLOSED

from sphinx-gallery.

The gallery reruns the examples which have changed. If you are constantly switching between branches that modifies the timestamps quite radically and many examples risk to be unnecessarily rerun.

PR #76 deals with this issue by checking file updates by md5sum, reducing the many unnecessary executions of scripts.

from sphinx-gallery.

Yes. I know that in theory it should only rebuild the changed examples. But
I think it is an unnecessary overhead on people who just want to contribute
one section of the doc. And at least for me I often end up fetching the
same branch on three different computers and don't want to rebuild on each
computer.

On Saturday, January 2, 2016, Óscar Nájera [email protected] wrote:

The gallery reruns the examples which have changed. If you are constantly
switching between branches that modifies the timestamps quite radically and
many examples risk to be unnecessarily rerun.

PR #76 deals with this issue by checking file updates by md5sum, reducing
the many unnecessary executions of scripts.

—
Reply to this email directly or view it on GitHub.<
https://ci6.googleusercontent.com/proxy/3ViFiPOc7VqKm94FqezzF8VrMxd3w4lqPUKM1lnyFkhwMNgd8rZ4CMDz-A7mKx2dWqUNPxJmlHMTXhEv8Hsx1dyY3OsIm4O8-PFyeK9LXWa6G2YVQsEaR3M4_FBxuDMadIc3p40YZreQRTsgorY4AoIY-XnTbw=s0-d-e1-ft#https://github.com/notifications/beacon/APHionzx4CdIhgM3bV2-fOzLZySJ-mi5ks5pVtX8gaJpZM4G9cIg.gif

from sphinx-gallery.

One other problem with rerunning only examples which have changed is that if you have an example failing the build (for missing package etc.), you end up having to recompute that example every time ... regardless of whether that's relevant to the section you are editing.

from sphinx-gallery.

from sphinx-gallery.

My point of view is that this is an anti-pattern, just like tests failing: a project should strive never to be in this situation.

I agree. But I fail to see why you would want to force someone who wants to contribute one section about spatial filters (or whatever their expertise) to install all the optional dependencies.

from sphinx-gallery.

from sphinx-gallery.

hmm ... I'm not convinced it's easy to build the docs. @agramfort we need to have a chat IRL :)

from sphinx-gallery.

Often people who contribute to the docs are not git ninjas and you don't want to make their life tougher by asking them to set up anaconda virtual environment by copying information from travis.yml on the dev branch of sphinx-gallery and dev branch of sphinx. Sometimes, even people using the package can contribute good docs (not just seasoned developers) and getting all this set up is information overload :)

from sphinx-gallery.

from sphinx-gallery.

There have been complains about this in the past where the main use case is to be able to run a single example and check whether the documentation (example + narrative documentation with potentially links and figures) looks fine. Quite often people doing this are not developers and this feels like a massive PITA for them to have to run all the examples, even only once.

Maybe we could make this simple use case easier, by providing a variable in conf.py which is a regex that the example filename must match, e.g. right now we have plot_.*.py hardcoded somewhere in our code. If we match the full filename rather than only basename we could even make the per-directory use case possible.

Full disclosure: I have seen one very inventive person hitting Control-C on all the examples but his own to be able to run the single example he cared about faster ...

from sphinx-gallery.

There have been complains about this in the past where the main use case is to be able to run a single example and check whether the documentation (example + narrative documentation with potentially links and figures) looks fine. Quite often people doing this are not developers and this feels like a massive PITA for them to have to run all the examples, even only once.

yes exactly!

Maybe we could make this simple use case easier, by providing a variable in conf.py which is a regex that the example filename must match, e.g. right now we have plot_.*.py hardcoded somewhere in our code. If we match the full filename rather than only basename we could even make the per-directory use case possible.

why not. Sounds like it could work.

Full disclosure: I have seen one very inventive person hitting Control-C on all the examples but his own to be able to run the single example he cared about faster ...

Lol, I ended up renaming my example and example dir to start with an a so that it was the first thing processed ;) But I think a proper fix would be really nice.

from sphinx-gallery.

Lol, I ended up renaming my example and example dir to start with an a so that it was the first thing processed ;) But I think a proper fix would be really nice.

I'm also considering. If it is for testing purposes, and you want to nevertheless mess up with the conf.py, why not put the particular examples you are testing in a separate folder, and by using the gallery ability to build multiple galleries, just to select your test folder, and skip the regular ones.
Something in the lines of:

sphinx_gallery_conf = {
    'examples_dirs': '../test_gallery', # '../examples'
    'gallery_dirs': 'auto_examples',
}

Later when it's all good, you put them in the desired place, remove the comment and all shall be fine.

from sphinx-gallery.

IMHO this seems like more messing around and more error prone than being able to specify a pattern that the example filename has to match.

from sphinx-gallery.

from sphinx-gallery.

from sphinx-gallery.

great, I think we converged upon a solution. Just so that I understand correctly, at the mne-python end it would mean using the - D option in sphinx-build to specify a pattern of files to build?

Does any of you want to make the PR or do you want to be reviewers? :)

from sphinx-gallery.

Just so that I understand correctly, at the mne-python end it would mean using the - D option in sphinx-build to specify a pattern of files to build?

This would be the same behaviour as the plot_gallery variable which is used to skip running the examples. So you can either set it in conf.py or with the -D option of sphinx-build.

Does any of you want to make the PR or do you want to be reviewers? :)

If you manage to find some time to put together a PR it will be greatly appreciated of course ! It doesn't seem that hard to do. You need to add a variable in sphinx_gallery_conf for the pattern that the filename is supposed to match, then change this line in order to read the variable from app.config.sphinx_gallery_conf and use it in order to decide whether the example should be run.

For genericity's sake, I'd be in favour of using re.search with a regex pattern that matches the absolute path of the example.

Let us know if you decide to work on a PR so that we don't end up duplicating efforts !

from sphinx-gallery.

Excellent, I'll give it a shot :)

from sphinx-gallery.