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

API documentations generated by sphinx 2.x are unreadable #305

Closed seisman closed 4 years ago

seisman commented 5 years ago

Description of the problem

See https://www.pygmt.org/dev/api/generated/pygmt.Figure.basemap.html or the screenshot below: image

This is caused by the recent update of sphinx 2.x and the inconsistence between sphinx 2.x and sphinx_rtd_theme. See https://github.com/rtfd/sphinx_rtd_theme/issues/752 for the description of the bug.

We should use sphinx<=1.8.5 now.

seisman commented 5 years ago

The API lists are not still rendered correctly. image

See https://www.pygmt.org/dev/api/index.html#plotting

leouieda commented 5 years ago

You're right. I hand't notice when that I downgraded. I'll try 1.8.3

seisman commented 5 years ago

1.8.5 works locally for me.

leouieda commented 5 years ago

From numpy/numpydoc#215 this problem seems to be a combination of sphinx, numpydoc, and the rtd theme. I get the same thing locally. For now, this is not good but not terrible. Let's keep this open so we know to fix it but I don't want to worry too much about it now.

weiji14 commented 4 years ago

I'll close this as it should be resolved by the move to using the napolean sphinx extension in #383. Screenshot of https://www.pygmt.org/dev/api/generated/pygmt.Figure.basemap.html and https://www.pygmt.org/dev/api/index.html#plotting below:

basemap docs with new napolean sphinx

plotting api docs with new napolean sphinx