Repository navigation
Conversation
Just as a remark: If we want to keep Sphinx-gallery for some reason, we could also place a gallery under users. We also don't have to use the tiled gallery entry page if we prefer a something else. One can ar least hide it and instead link from a custom overview page. |
|
@timhoffm yes that makes sense. I also wonder if it is possible to mix rst and py files in a "gallery" - perhaps that's a better way to do all this. On the other hand, I think it's still worth looking into how to add the hi res plots to our plot directive like we did for sphinx gallery. |
|
Just to follow up on this - it may indeed be possible to put a gallery under /users/, but it is not possible, so far as I can tell, to add bare To be more explicit: adding So, we have the conundrum that if we keep the tutorials as tutorials they would have to be in a different directory, and if we move them to be rst, then there two disadvantages above would be present. I think making the plot_directive output hires is easy-ish. I am not sure that making plot directive objects global to the rest of the file is going to be easy though. I think perhaps the best solution for now is to add individual tutorials to the table of contents under |
I think that's one of the most useful features of sphinx gallery and one of my concerns about moving things out of gallery is losing the thumbnails. A major advantage of viz stuff is you don't need to know what it's called, just need to find the picture that looks like what you're trying to do. |
|
I don't personally think we should get rid of the Gallery or the tutorials. Just curate them a bit, and some of the tutorials could optionally move over into users. However, I think that is less urgent given how #24987 looks in the docs, where the tutorials don't look like tutorials in the sidebar navigation when referenced from |
PR Summary
This is a test to see how easy it is to move a tutorial into the users docs, making it a native rst file instead of using sphinx-gallery. Turns out its pretty easy, with a couple of important caveats...
All that was done here was to run sphinx gallery on
/tutorials/intermediate/arranging_axes.pyand then hand-edited thearranging_axes.rstto replace.. code-block:: defaultwithand then remove the
.. image-sg ::directives.Note, that I'm not arguing we should get rid of sphinx gallery. However, many of the explanatory tutorials should probably be logically be under
/users. This is just a proof of concept to see what such a migration would look likePR Checklist
Documentation and Tests
pytestpasses)Release Notes
.. versionadded::directive in the docstring and documented indoc/users/next_whats_new/.. versionchanged::directive in the docstring and documented indoc/api/next_api_changes/next_whats_new/README.rstornext_api_changes/README.rst