Repository navigation
Convert remaining narrative docs to tutorials #19688
Description
The following docs should be converted to tutorials.
docs/users/interactive.rstdocs/users/interactive_guide.rstdocs/users/event_handling.rst
They are the only narrative docs that is not a tutorial, and thus are hard to find. While they could use some work, moving them as is would already be a net win for discoverability.
Reacted by hannah and Jody Klymak
Activity
jklymak commentedon Mar 11, 2021
Does sphinx-gallery allow bare rst files in the python directory? That would be easiest (plus a redirect).
timhoffm commentedon Mar 12, 2021
I don't think so. It's probably renaming to .py and adding comments in front of every line, or
.. include: interactive.rst.rajpratyush commentedon Mar 12, 2021
Can I take up this issue? @timhoffm
timhoffm commentedon Mar 13, 2021
Go for it.
tacaswell commentedon Aug 22, 2021
I think we should be pushing things the other way and converting more tutorials to be adjacent to these (to separate out the "how to do a task" from "understand how Matplotlib views the world".
jklymak commentedon Aug 22, 2021
To me the current division is whether the page is made via Sphinx gallery or as rst. Ideally there would be a way to combine technology (or even better allow notebooks)
story645 commentedon Aug 22, 2021
@jklymak https://nbsphinx.readthedocs.io/en/0.6.1/subdir/gallery.html
And also then would that division be
which is a bit medium guides the message & I think could either work really well to set expectations on content for each section or end up really clunky.
anntzer commentedon Aug 22, 2021
fwiw I would also much prefer if s-g could be made to support .rst files, just for editing convenience (e.g. I have better syntax highlighting, and shortcut for directly converting a single rst to html (obviously, some links will be broken, but you still catch plenty of simple rst syntax errors in that way)).
timhoffm commentedon Aug 22, 2021
sphinx-gallery/sphinx-gallery#330
jklymak commentedon Aug 22, 2021
I guess I was thinking even simpler - just support the rst files directly without worrying about backlinks etc.
However, those links are useful in pointing out that its probably OK to just have an rst->py converter that would only need to be run once to make the files such that s-g could render them.
The overarching point is that it would be nice if our docs were not organized by the rendering technology, which is why "Users Guide" is different than "Tutorials" currently.
timhoffm commentedon Aug 23, 2021
I'm closing this issue because it's not clear how we want to origanize the different doc types. For now, we won't convert the existing narrative docs. At least they are put in a better location by #20867.