Suppress the sphinx + sphinx-gallery warnings

[seisman]

Does anyone have any recommendations for suppressing the warnings like this:

WARNING: multiple files found for the document "gallery/coast/land_and_water": ['gallery/coast/land_and_water.py', 'gallery/coast/land_and_water.ipynb', 'gallery/coast/land_and_water.py.md5', 'gallery/coast/land_and_water.rst']

They are a bit distracting.

Originally posted by @meghanrjones in #875 (comment)

I agree, perhaps you can try if adding them to exclude_patterns in doc/conf.py works.

Originally posted by @seisman in #875 (comment)

[maxrjones]

Is there a reason for these to get built in, for example, gallery/coast/ rather than a subdirectory in _build/?

[seisman]

I have no idea. The gallery was set up by @leouieda (#268). Not sure if sphinx-gallery can generate these files in _build.

BTW, it seems possible to remove the nbsphinx extension, as mentioned in #268 (comment).

[maxrjones]

OK, thanks. I will try to figure this out, but anyone is welcome to help.

[seisman]

BTW, it seems possible to remove the nbsphinx extension, as mentioned in #268 (comment).

Also see #269 (comment)

[maxrjones]

Thanks. Yes, these warnings are caused by the nbsphinx extension. doc/conf.py sets source_suffix = ".rst", but this info that's reported while building the docs indicates that nbsphinx resets this to source_suffix = "":

updating environment: [config changed ('source_suffix')] 149 added, 0 changed, 0 removed

After reading #268 (comment) and #269 (comment), I still do not understand why we need nbsphinx. Is the "one notebook tutorial that shows how to use PyGMT with the notebook" referring to examples/tutorials/first-figure.py or something else? I did not notice anything in the docs that looks different when building the docs without nbsphinx.

[maxrjones]

Also, adding the file extensions to exclude_patterns in doc/conf.py suppresses the warnings, but I think it would be better to fix this by removing nbsphinx if it is not needed.

[seisman]

After reading #268 (comment) and #269 (comment), I still do not understand why we need nbsphinx. Is the "one notebook tutorial that shows how to use PyGMT with the notebook" referring to examples/tutorials/first-figure.py or something else? I did not notice anything in the docs that looks different when building the docs without nbsphinx.

When @leouieda started this project, the tutorials were written in notebooks using nbsphinx (see the old notebooks at https://github.com/GenericMappingTools/pygmt/tree/e5845ba38df2b4c04a55132df0edede05ca29321/doc/tutorials). In #268, we switched to sphinx-gallery (i.e., using .py files) so that the nbsphinx is no longer necessary and can be removed.

The reason that @leouieda kept the nbsphinx extension, is because the idea of new design of Figure.show() in #269. In the new design in #269, I think @leouieda proposed to always open previews in external viewers, and in Jupyter notebooks, users need to call pygmt.enable_notebook() to disable external viewer or enable notebook display. So he wanted to add a jupyter notebook to show how pygmt.enable_notebook() works for Jupyter users.

However, I believe it's no longer necessary after we finish the new design of Figure.show() in #529 (still work in process, but should be ready before v0.4.0).

So I think we should remove the nbsphinx extension.