search

GenericMappingTools / pygmt

A Python interface for the Generic Mapping Tools.
https://www.pygmt.org
BSD 3-Clause "New" or "Revised" License
747 stars 216 forks source link

Suppress the sphinx + sphinx-gallery warnings #920

Closed seisman closed 3 years ago

seisman commented 3 years ago

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 https://github.com/GenericMappingTools/pygmt/issues/875#issuecomment-778420989

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

Originally posted by @seisman in https://github.com/GenericMappingTools/pygmt/issues/875#issuecomment-778434040

maxrjones commented 3 years ago

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

seisman commented 3 years ago

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 https://github.com/GenericMappingTools/pygmt/pull/268#discussion_r250684321.

maxrjones commented 3 years ago

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

seisman commented 3 years ago

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

Also see https://github.com/GenericMappingTools/pygmt/issues/269#issuecomment-457260318

maxrjones commented 3 years ago

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 https://github.com/GenericMappingTools/pygmt/pull/268#discussion_r250684321 and https://github.com/GenericMappingTools/pygmt/issues/269#issuecomment-457260318, 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 commented 3 years ago

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 commented 3 years ago

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.