Doc: sg section separator #25021
Doc: sg section separator #25021
Conversation
| displayed, and figures are put into the built page. | ||
| displayed, and figures are put into the built page. Matplotlib uses the | ||
| ``# %%`` section separator so that IDEs will identify "code cells" to make | ||
| it easy to re-run sub-sections of the example. |
There was a problem hiding this comment.
There is an example of a tutorial below this which still has the long line. Edit: and the description right above it talks about a line of #.
There was a problem hiding this comment.
🤦🏻 I looked for our documentation on how to split sections and was a bit surprised we did not have any. I am glad the problem was me and not our docs! Thank you for catching this.
There was a problem hiding this comment.
what about adding a subsection heading at L814 "Formatting Examples" - it seems redundant in prose, but might be useful in the right hand side navigation
2ea17e2 to
c3e77c3
Compare
There was a problem hiding this comment.
I think this is fine, but I don't think we should merge until we discuss and make sure everyone is onboard with the change. So I'm just blocking until a few more people weight in with up or down thumbs or checkmarks.
My only objection is that I find it less readable, but it's not terrible.
I'm 👍 because this separator is far harder to mess up than the very long line of hashes where I'm never quite sure how many. (Yes, I mark 80 in vs code and go to that line, but I don't know if that's a thing in other editors). Also, like @tacaswell and @kolibril13 mentioned, it makes blockwise execution trivial in a bunch of IDEs and that rapid iteration is super useful. |
| displayed, and figures are put into the built page. | ||
| displayed, and figures are put into the built page. Matplotlib uses the | ||
| ``# %%`` section separator so that IDEs will identify "code cells" to make | ||
| it easy to re-run sub-sections of the example. |
There was a problem hiding this comment.
what about adding a subsection heading at L814 "Formatting Examples" - it seems redundant in prose, but might be useful in the right hand side navigation
This is so that IDEs will auto detect "cells" and make (re) running sub sections of the code easier for development and debugging.
c3e77c3 to
e5f0066
Compare
|
Going to ignore the Azure pipeline, as it timed out there, but didn't post the result ot GitHub, so I can't even restart it. Plus this is all docs. |
…rom examples Manual backport of matplotlib#25198 due to conflicts in examples/subplots_axes_and_figures/demo_constrained_layout.py This was because some of the changes here were right below the section separators which changed in main at matplotlib#25021.
PR Summary
Prompted by #25016 this changes all of our SG section separators to
# %%and documents that this is our preference.