Add processing of literal blocks in try examples directive #134
Conversation
|
This isn't quite working yet. Still some edge cases to work out. Marking as draft. |
Case where the next line after a literal block opens another literal block.
|
It's working now. Here's a link https://steppi.github.io/scipy/reference/generated/scipy.integrate.quad.html#scipy.integrate.quad. I didn't correctly handle the case where a literal block directly follows another literal block. |
| @@ -216,6 +216,50 @@ def _process_latex(md_text): | |||
| return "\n".join(wrapped_lines) | |||
|
|
|||
|
|
|||
| def _process_literal_blocks(md_text): | |||
| md_lines = md_text.split("\n") | |||
There was a problem hiding this comment.
Dumb questions, but how will this behave on windows where the line separator may be \r\n ? Or is it always \n in sphinx ? maybe:
| md_lines = md_text.split("\n") | |
| md_lines = md_text.splitlines() |
I know there are other differences like if there is a terminal \n, or empty string.
There was a problem hiding this comment.
It's a good question. Basically yes, I think we can always assume it's '\n' in Sphinx. Changing to splitlines won't affect the outcome, but it seems like a good change to make just because it better demonstrates intent.
The details: Python's open function has a newline kwarg whose default behavior is to normalize all line breaks to '\n', and this is what is used in Sphinx. So in Sphinx it's always '\n', regardless of the convention used by the RST files themselves. From the docs for open:
newline determines how to parse newline characters from the stream. It can be None, '', '\n', '\r', and '\r\n'. It works as follows:
When reading input from the stream, if newline is None, universal newlines mode is enabled. Lines in the input can end in '\n', '\r', or '\r\n', and these are translated into '\n' before being returned to the caller. If it is '', universal newlines mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.*
When writing output to the stream, if newline is None, any '\n' characters written are translated to the system default line separator, os.linesep. If newline is '' or '\n', no translation takes place. If newline is any of the other legal values, any '\n' characters written are translated to the given string.
I think the only difference we'd see using splitlines() vs split('\n') is that, like you said, the former ignores terminal newlines, and I don't think this actually would make a difference. I think Jupyter just ignores trailing newlines in markdown cells.
This PR adds support for processing literal blocks when converting RST to notebooks in the
TryExamplesDirective. I noticed these weren't being handled correctly while going over locally built SciPy docs carefully in preparation for submitting a PR to SciPy. Screenshot below of what can go wrong when literal blocks aren't handled correctly. I'll post a link to this example after this fix is in once it finishes building and is deployed.