Convert tutorials from sphinx-gallery to plain rst #31
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The tutorials have much more text than Python code so rendering them in sphinx-gallery means writing a bunch of rst content as comments in the `.py` files, which is very awkward. Use jupyter-sphinx instead so we can have the tutorials as plain rst files with code blocks executed by the extension. The output looks pretty much the same with some slight differences in style (had to tweak the CSS to match). Another advantage is that the "Edit on GitHub" links from sphinx-book-theme now work for these (they don't for the gallery output).
|
Before I review it, I must say that I'm amazed with |
|
I'm having some errors when building the docs, I think they are coming from GMT. Are you experiencing the same? |
|
Yes! The one thing I would miss from using sphinx-gallery was the liking of functions to their docs. With this, we can have it with jupyter-sphinx as well. For Ensaio it doesn't really matter since there aren't any long form tutorials. But for the other packages this is major. Just built the docs on a completely fresh environment with no issues. This is my Same GMT (6.2) and PyGMT (0.5) as you. Not sure what happened for you there since the CI also seems to build. |
|
I still can't build the docs 😢 I even reinstalled mambaforge and created the environment from scratch... without success. Our environments are the same (except for a different minor version of curl). I'm kind of lost here. But if CIs and you can build them, there might be something wrong in my end. |
|
😢 the error seems to be coming from ghostscript during the rendering of the postscript file to PNG. But our ghostscript versions are the same. I wonder if GMT is getting ghostscript from the systems instead of conda? |
|
Still having trouble with this? |
|
Merging in since CIs are happy. If it turns out to be a persistent problem we can investigate in a follow up. |
|
Yesterday I found that the problem is not with this PR only, but for some reason I also get it when trying to build the docs on |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
The tutorials have much more text than Python code so rendering them in sphinx-gallery means writing a bunch of rst content as comments in the
.pyfiles, which is very awkward. Use jupyter-sphinx instead so we can have the tutorials as plain rst files with code blocks executed by the extension. The output looks pretty much the same with some slight differences in style (had to tweak the CSS to match). Another advantage is that the "Edit on GitHub" links from sphinx-book-theme now work for these (they don't for the gallery output).Trying this out after @santisoler mentioned using this with the Harmonica docs refactor. I really like it and it looks like we can also add links to the API docs (with backreferences) using this extension in the future: https://github.com/felix-hilden/sphinx-codeautolink/ (need to get it on conda-forge).