search

GenericMappingTools / pygmt

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

Errors building docs on Apple M1 #2407

Closed maxrjones closed 1 year ago

maxrjones commented 1 year ago

Description of the problem

Since last year, I haven't been able to build the PyGMT docs locally on my M1 MacBook. The same steps work fine on a Linux VM and no online solutions have worked except changing the imports layout so that the methods are within the class rather than importing outside the top-level.

Minimal Complete Verifiable Example

cd <pygmt-repo>
mamba env create --file environment.yml
mamba activate pygmt
make install
cd doc
make html-noplot

Full error message

make html-noplot

Generating rst source files of API documentation.

sphinx-autogen -i -t _templates -o api/generated api/*.rst
[autosummary] generating autosummary for: api/index.rst
[autosummary] writing to api/generated
WARNING: [autosummary] failed to import 'pygmt.Figure.basemap': no module named pygmt.Figure.basemap
WARNING: [autosummary] failed to import 'pygmt.Figure.coast': no module named pygmt.Figure.coast
WARNING: [autosummary] failed to import 'pygmt.Figure.colorbar': no module named pygmt.Figure.colorbar
WARNING: [autosummary] failed to import 'pygmt.Figure.contour': no module named pygmt.Figure.contour
WARNING: [autosummary] failed to import 'pygmt.Figure.grdcontour': no module named pygmt.Figure.grdcontour
WARNING: [autosummary] failed to import 'pygmt.Figure.grdimage': no module named pygmt.Figure.grdimage
WARNING: [autosummary] failed to import 'pygmt.Figure.grdview': no module named pygmt.Figure.grdview
WARNING: [autosummary] failed to import 'pygmt.Figure.histogram': no module named pygmt.Figure.histogram
WARNING: [autosummary] failed to import 'pygmt.Figure.image': no module named pygmt.Figure.image
WARNING: [autosummary] failed to import 'pygmt.Figure.inset': no module named pygmt.Figure.inset
WARNING: [autosummary] failed to import 'pygmt.Figure.legend': no module named pygmt.Figure.legend
WARNING: [autosummary] failed to import 'pygmt.Figure.logo': no module named pygmt.Figure.logo
WARNING: [autosummary] failed to import 'pygmt.Figure.meca': no module named pygmt.Figure.meca
WARNING: [autosummary] failed to import 'pygmt.Figure.plot': no module named pygmt.Figure.plot
WARNING: [autosummary] failed to import 'pygmt.Figure.plot3d': no module named pygmt.Figure.plot3d
WARNING: [autosummary] failed to import 'pygmt.Figure.psconvert': no module named pygmt.Figure.psconvert
WARNING: [autosummary] failed to import 'pygmt.Figure.rose': no module named pygmt.Figure.rose
WARNING: [autosummary] failed to import 'pygmt.Figure.savefig': no module named pygmt.Figure.savefig
WARNING: [autosummary] failed to import 'pygmt.Figure.set_panel': no module named pygmt.Figure.set_panel
WARNING: [autosummary] failed to import 'pygmt.Figure.shift_origin': no module named pygmt.Figure.shift_origin
WARNING: [autosummary] failed to import 'pygmt.Figure.show': no module named pygmt.Figure.show
WARNING: [autosummary] failed to import 'pygmt.Figure.solar': no module named pygmt.Figure.solar
WARNING: [autosummary] failed to import 'pygmt.Figure.subplot': no module named pygmt.Figure.subplot
WARNING: [autosummary] failed to import 'pygmt.Figure.ternary': no module named pygmt.Figure.ternary
WARNING: [autosummary] failed to import 'pygmt.Figure.text': no module named pygmt.Figure.text
WARNING: [autosummary] failed to import 'pygmt.Figure.timestamp': no module named pygmt.Figure.timestamp
WARNING: [autosummary] failed to import 'pygmt.Figure.velo': no module named pygmt.Figure.velo
WARNING: [autosummary] failed to import 'pygmt.Figure.wiggle': no module named pygmt.Figure.wiggle
WARNING: [autosummary] failed to import 'pygmt.clib.Session.__enter__': no module named pygmt.clib.Session.__enter__
WARNING: [autosummary] failed to import 'pygmt.clib.Session.__exit__': no module named pygmt.clib.Session.__exit__
WARNING: [autosummary] failed to import 'pygmt.clib.Session.__getitem__': no module named pygmt.clib.Session.__getitem__
WARNING: [autosummary] failed to import 'pygmt.clib.Session.call_module': no module named pygmt.clib.Session.call_module
WARNING: [autosummary] failed to import 'pygmt.clib.Session.create': no module named pygmt.clib.Session.create
WARNING: [autosummary] failed to import 'pygmt.clib.Session.create_data': no module named pygmt.clib.Session.create_data
WARNING: [autosummary] failed to import 'pygmt.clib.Session.destroy': no module named pygmt.clib.Session.destroy
WARNING: [autosummary] failed to import 'pygmt.clib.Session.extract_region': no module named pygmt.clib.Session.extract_region
WARNING: [autosummary] failed to import 'pygmt.clib.Session.get_default': no module named pygmt.clib.Session.get_default
WARNING: [autosummary] failed to import 'pygmt.clib.Session.get_libgmt_func': no module named pygmt.clib.Session.get_libgmt_func
WARNING: [autosummary] failed to import 'pygmt.clib.Session.open_virtual_file': no module named pygmt.clib.Session.open_virtual_file
WARNING: [autosummary] failed to import 'pygmt.clib.Session.put_matrix': no module named pygmt.clib.Session.put_matrix
WARNING: [autosummary] failed to import 'pygmt.clib.Session.put_strings': no module named pygmt.clib.Session.put_strings
WARNING: [autosummary] failed to import 'pygmt.clib.Session.put_vector': no module named pygmt.clib.Session.put_vector
WARNING: [autosummary] failed to import 'pygmt.clib.Session.virtualfile_from_data': no module named pygmt.clib.Session.virtualfile_from_data
WARNING: [autosummary] failed to import 'pygmt.clib.Session.virtualfile_from_grid': no module named pygmt.clib.Session.virtualfile_from_grid
WARNING: [autosummary] failed to import 'pygmt.clib.Session.virtualfile_from_matrix': no module named pygmt.clib.Session.virtualfile_from_matrix
WARNING: [autosummary] failed to import 'pygmt.clib.Session.virtualfile_from_vectors': no module named pygmt.clib.Session.virtualfile_from_vectors
WARNING: [autosummary] failed to import 'pygmt.clib.Session.write_data': no module named pygmt.clib.Session.write_data

Building HTML files without example plots.

sphinx-build -D plot_gallery=0 -b html -d _build/doctrees  -j auto . _build/html
Running Sphinx v4.3.2
For security reasons, parallel mode is disabled on macOS and python3.8 and above. For more details, please read https://github.com/sphinx-doc/sphinx/issues/6803
WARNING: The config value `plot_gallery' has type `str', defaults to `bool'.
loading pickled environment... done
myst v0.18.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=['colon_fence'], disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=4, heading_slug_func=None, footnote_transition=True, words_per_minute=200, sub_delimiters=('{', '}'), linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area')
generating gallery...
Using Sphinx-Gallery to convert rst text blocks to markdown for .ipynb files.
generating gallery for gallery/maps... [100%] shorelines.py                     
generating gallery for gallery/lines... [100%] wiggle.py                        
generating gallery for gallery/symbols... [100%] bars.py                        
generating gallery for gallery/images... [100%] track_sampling.py               
generating gallery for gallery/3d_plots... [100%] grdview_surface.py            
generating gallery for gallery/seismology... [100%] velo_arrow_ellipse.py       
generating gallery for gallery/basemaps... [100%] ternary.py                    
generating gallery for gallery/histograms... [100%] rose.py                     
generating gallery for gallery/embellishments... [ 57%] inset_rectangle_region.pgenerating gallery for gallery/embellishments... [100%] colorbars_multiple.py   
generating gallery for tutorials/basics... [100%] regions.py                    
generating gallery for tutorials/advanced... [100%] vectors.py                  
generating gallery for get_started... [100%] 02_contour_map.py                  
generating gallery for projections/azim... [100%] azim_orthographic.py          
generating gallery for projections/conic... [100%] polyconic.py                 
generating gallery for projections/cyl... [100%] cyl_universal_transverse_mercator.py
generating gallery for projections/misc... [100%] misc_winkel_tripel.py         
generating gallery for projections/nongeo... [100%] polar.py                    
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 170 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] tutorials/index                                        y_gradient
generating indices... genindex py-modindex done
highlighting module code... [100%] pygmt.src.xyz2grd                            t
writing additional pages... search done
copying images... [100%] _static/agu2017-poster.jpg                             g_thumb.pngmb.pngthumb.png
copying downloadable files... [100%] tutorials/basics/text.ipynb                nbbtor.ipynb
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in _build/html.
Sphinx-Gallery gallery_conf["plot_gallery"] was False, so no examples were executed.
embedding documentation hyperlinks...
embedding documentation hyperlinks for gallery... [100%] double_y_axes.html     htmll
embedding documentation hyperlinks for tutorials... [100%] date_time_charts.htmlltml
embedding documentation hyperlinks for get_started... [100%] 02_contour_map.htmll
embedding documentation hyperlinks for projections... [100%] conic_equidistant.html.htmllcator.html

Build finished. The HTML pages are in _build/html.

System information

PyGMT information:
  version: v0.8.1.dev72+gb7926aef4
System information:
  python: 3.11.0 | packaged by conda-forge | (main, Jan 14 2023, 12:26:40) [Clang 14.0.6 ]
  executable: /opt/homebrew/Caskroom/miniforge/base/envs/pygmt/bin/python
  machine: macOS-13.2.1-arm64-arm-64bit
Dependency information:
  numpy: 1.24.2
  pandas: 1.5.3
  xarray: 2023.2.0
  netCDF4: 1.6.3
  packaging: 23.0
  contextily: 1.3.0
  geopandas: 0.12.2
  ghostscript: 9.54.0
GMT library information:
  binary version: 6.4.0
  cores: 8
  grid layout: rows
  library path: /opt/homebrew/Caskroom/miniforge/base/envs/pygmt/lib/libgmt.dylib
  padding: 2
  plugin dir: /opt/homebrew/Caskroom/miniforge/base/envs/pygmt/lib/gmt/plugins
  share dir: /opt/homebrew/Caskroom/miniforge/base/envs/pygmt/share/gmt
  version: 6.4.0
weiji14 commented 1 year ago

Hmm, wondering if it's a sphinx issue. A quick search yielded https://github.com/sphinx-doc/sphinx/issues/10943 and https://stackoverflow.com/questions/73372315/autosummary-fails-to-import-the-methods-from-the-package-classes-locally which looks related? Something about the docs build not working when the package is installed in editable mode.

maxrjones commented 1 year ago

Thanks @weiji14! I hadn't thought to try a non-editable install. That runs without errors, so I'll close this as an upstream issue.

maxrjones commented 1 year ago

If we wanted an automatic workaround we could modify the sphinx Makefile as in https://github.com/alteryx/featuretools/pull/2367, but this is an uncommon issue and that would slow builds down for all other cases so I don't think it's necessary.