New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BUG: Spamming of warnings about `.exclude` #126

Closed
larsoner opened this Issue Jun 8, 2016 · 11 comments

Comments

Projects
None yet
3 participants
@larsoner
Contributor

larsoner commented Jun 8, 2016

Currently my build gets hundreds of these lines:

/home/larsoner/custombuilds/mne-python/doc/generated/mne.write_labels_to_annot.rst:8: SEVERE: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'generated/mne.write_labels_to_annot.examples'.

It makes it difficult to find the actual useful Sphinx warnings.

I think it comes from:

doc/_templates/module.rst:   .. include:: {{fullname}}.{{item}}.examples

Is there a way to have the template only include the .examples file if it exists, or by default filter out any warnings in sphinx that occur of this form?

@Titan-C

This comment has been minimized.

Member

Titan-C commented Jun 8, 2016

Which version are you using? This should have been fixed in #96

@larsoner

This comment has been minimized.

Contributor

larsoner commented Jun 8, 2016

I am using latest master. I think there is some path problem. Looking at e.g.:

/home/larsoner/custombuilds/mne-python/doc/generated/mne.concatenate_events.rst

It is in doc/generated.

The touch_empty_backreferences function looks for (according to a print debug statement I added) and creates a file in doc/modules/generated instead, though:

/home/larsoner/custombuilds/mne-python/doc/modules/generated/mne.concatenate_events.examples

Does that make sense?

@larsoner

This comment has been minimized.

Contributor

larsoner commented Jun 8, 2016

Specifically, it looks like app.srcdir is correct with /home/larsoner/custombuilds/mne-python/doc, but then the app.config.sphinx_gallery_conf["mod_example_dir"] is incorrect (or is being incorrectly used) as it's modules/generated, but the files that have the .. include statement land in generated/.

I don't know why this would work for other repos and not MNE-Python's, though -- I don't think we do anything special really. And git grep mod_example_dir in MNE-Python yields nothing.

@Titan-C do you not get these warnings? What is your app.srcdir and app.config.sphinx_gallery_conf['mod_example_dir']?

If I put 'mod_example_dir': 'generated' (overriding the default (modules/generated) the warnings go away for me, so there is at least a workaround in the meantime.

@Titan-C Titan-C added the bug label Jun 19, 2016

@Titan-C

This comment has been minimized.

Member

Titan-C commented Jul 10, 2016

What is the status in here? I had the memory of having answered to this one. I see from the merged code to your project that you have copied the function touch_empty_backreferences to your conf.py although is already in sphinx-gallery.
The complete point is to have 'mod_example_dir' the place where you write the auto generated examples. modules/generated is default because that is the structure that scikit-learn uses
I would like to ask for help on rewriting the documentation. Why is it not clear from this section? http://sphinx-gallery.readthedocs.io/en/latest/advanced_configuration.html#establishing-local-references-to-examples what to do?

@Titan-C Titan-C added help wanted Easy Fix and removed bug labels Jul 10, 2016

@larsoner

This comment has been minimized.

Contributor

larsoner commented Jul 10, 2016

I see from the merged code to your project that you have copied the function touch_empty_backreferences

In mne-python? I don't see it in master anywhere, and git grep backref in project root is empty.

The complete point is to have 'mod_example_dir' the place where you write the auto generated examples. modules/generated is default because that is the structure that scikit-learn uses
I would like to ask for help on rewriting the documentation. Why is it not clear from this section? http://sphinx-gallery.readthedocs.io/en/latest/advanced_configuration.html#establishing-local-references-

The problem, so far as I can tell, is just that using the defaults (which we had been doing) results in a ton of warnings. The solution for our repo, which AFAIK uses all defaults for just about everything else, has been to make 'mod_example_dir': 'generated' the default. It doesn't seem like "using all defaults" should result in all these warning messages, but I think that's the state of things currently, right?

I just pulled latest master and reconfirmed that removing 'mod_example_dir': 'generated' from our conf (which I put in to get rid of the warnings) brings back the warning spam messages.

@larsoner

This comment has been minimized.

Contributor

larsoner commented Jul 10, 2016

... so the solutions I guess would be to modify mod_example_dir default value, or to modify touch_empty_backreferences to be smarter about what it touches...?

@larsoner

This comment has been minimized.

Contributor

larsoner commented Aug 5, 2016

I'd be happy to fix this one if we settle on one of the options I mentioned.

@Titan-C

This comment has been minimized.

Member

Titan-C commented Aug 5, 2016

Sorry for not keeping up with this issue. I think this is really more a documentation issue, on the correct use of Sphinx-Gallery with autodoc and autosummary from Sphinx.
The reason why on mne-python you can't use the Sphinx-Gallery default is because:
In your file doc/python_reference.rst you use:

.. autosummary::
   :toctree: generated/
   :template: function.rst

The directory defined in toctree is where autosummary stores the rst files containing you function API, according to the template that you have in doc/_templates/function.rst. There you have written

.. include:: {{module}}.{{objname}}.examples

That means it will look locally for the example back_references files.

... so the solutions I guess would be to modify mod_example_dir default value, or to modify touch_empty_backreferences to be smarter about what it touches...?

There are certainly many solutions:

  • mod_example_dir default, should be put under discussion. I think setting it to None. To only trigger the backreference generator once this value is consciously set by the user.
  • You can change doc/python_reference.rst to use :toctree: modules/generated
  • You can change doc/_templates/function.rst to use the correct relative path
.. include:: ../modules/generated/{{module}}.{{objname}}.examples
  • Set as you already do the good value for mod_example_dir
  • Changing touch_empty_backreferences is a no go for me
  • Improve the documentation is for me the way to go.
@larsoner

This comment has been minimized.

Contributor

larsoner commented Aug 5, 2016

Ahh, so it's a mis-configuration of our files. I'll probably change python_reference.rst or _templates/function.rst, since that seems better than changing mod_example_dir in our conf. Sorry for the noise, and thanks for the help.

@Titan-C

This comment has been minimized.

Member

Titan-C commented Aug 5, 2016

Ahh, so it's a mis-configuration of our files

Is not a misconfiguration, is a setup choice. I would think on setting mod_example_dir to None as default so to force the user to setup all the Sphinx autosummary stuff together with this variable.

@GaelVaroquaux @lesteve any thoughts on this?

@lesteve

This comment has been minimized.

Contributor

lesteve commented Aug 8, 2016

If I understand correctly you need some settings in your autosummary to match the 'mod_example_dir' settings in conf.py. I am not a sphinx expert but off the top of my head, I don't see any non-hacky way to set the latter automatically so the only thing we can do is improve the documentation.

I would think on setting mod_example_dir to None as default so to force the user to setup all the Sphinx autosummary stuff together with this variable.

Maybe this is the most reasonable thing to do.

@Titan-C Titan-C added this to the Release V0.1.5 milestone Sep 4, 2016

Titan-C added a commit to Titan-C/sphinx-gallery that referenced this issue Nov 27, 2016

Build gallery when example has SyntaxError
As reported in sphinx-gallery#126 if an example has a SyntaxError gallery build
breaks. This provides the necessary changes to continue build and
raise an error at the end on the summary of errors

Titan-C added a commit to Titan-C/sphinx-gallery that referenced this issue Dec 17, 2016

Build gallery when example has SyntaxError
As reported in sphinx-gallery#126 if an example has a SyntaxError gallery build
breaks. This provides the necessary changes to continue build and
raise an error at the end on the summary of errors

Titan-C added a commit to Titan-C/sphinx-gallery that referenced this issue Dec 17, 2016

Build gallery when example has SyntaxError
As reported in sphinx-gallery#126 if an example has a SyntaxError gallery build
breaks. This provides the necessary changes to continue build and
raise an error at the end on the summary of errors

Titan-C added a commit to Titan-C/sphinx-gallery that referenced this issue Dec 17, 2016

Build gallery when example has SyntaxError
As reported in sphinx-gallery#126 if an example has a SyntaxError gallery build
breaks. This provides the necessary changes to continue build and
raise an error at the end on the summary of errors

Titan-C added a commit to Titan-C/sphinx-gallery that referenced this issue Dec 17, 2016

Build gallery when example has SyntaxError
As reported in sphinx-gallery#126 if an example has a SyntaxError gallery build
breaks. This provides the necessary changes to continue build and
raise an error at the end on the summary of errors

lesteve added a commit that referenced this issue Dec 18, 2016

Build gallery when example has SyntaxError (#177)
As reported in #126 if an example has a SyntaxError gallery build
breaks. This provides the necessary changes to continue build and
raise an error at the end on the summary of errors

@Titan-C Titan-C modified the milestones: Release V0.1.9, Release v0.1.8 Jan 3, 2017

@dopplershift dopplershift referenced this issue Jan 7, 2017

Closed

Documentation upgrades part 2 #285

7 of 9 tasks complete

@Titan-C Titan-C closed this in #151 Apr 9, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment