API documentations generated by sphinx 2.x are unreadable

[seisman]

Description of the problem

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

This is caused by the recent update of sphinx 2.x and the inconsistence between sphinx 2.x and sphinx_rtd_theme. See readthedocs/sphinx_rtd_theme#752 for the description of the bug.

We should use sphinx<=1.8.5 now.

[seisman]

The API lists are not still rendered correctly.

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

[leouieda]

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

[seisman]

1.8.5 works locally for me.

[leouieda]

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]

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: