-
Notifications
You must be signed in to change notification settings - Fork 130
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Centered equations not rendering properly #155
Comments
What Sphinx version are you using? This looks like a bug from versions < 1.4.2, see #44 and sphinx-doc/sphinx#2473 and sphinx-doc/sphinx#2476. |
Hmmm, that's strange. I don't know what exactly is going wrong here, but probably having a look at the intermediary RST file gives us a clue. Can you please check out the BTW, I've given the wrong reference #44 above. For Markdown cells, the "nowrap" thing was introduced in #43 and updated in #110. |
Sorry, I'm not quite following. I checked out save-rst, navigated to the docs directory, and ran There are no intermediate .rst in the _build dir; I even verified that The html for the centered equation is: <span class="math" id="MathJax-Span-12" aria-hidden="true" style="vertical-align: 0.215em;">
<span class="noError" id="MathJax-Span-13" style="display: inline-block;">
"\begin{align}\begin{aligned}�:nowrap:�\\\begin{equation}"
<br>
"\int_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0)"
<br>
"\end{equation}\end{aligned}\end{align}"
</span>
</span> |
You should follow the instructions in CONTRIBUTING.rst to get a development installation of the |
Ah! Of course. |
Hmmm, one strange thing is that you seem to have additional blank lines between each line ... Can you please check with a hex-editor if the "newlines" are CRLF or LF or alternating or something else? Which OS and which Python version are you using? Or maybe this has something to do with Finally, can you please try to insert this line right before the last print(repr(rststring)) ... and run Sphinx again (probably using the |
mmhh.. Line 886?
so the 'Special marker characters are removed below' aren't removed? #109 In the intermediate rst the '\x0e:nowrap:\x0f\n\n still remains... |
Sorry my responses are delayed. I wish I could address this stuff while I was at work :/ Yes, every line in the rst has an extra line. The newlines in the intermediate .rst file is CRLF. I'm running:
This is the output of the repr:
|
Thanks for the additional information, I think we found the problem! You are getting:
... but I am (or rather the regular expression is) expecting:
This is caused by Windows using CRLF, but I'm not sure if the The question now is if we should try to remove the dreaded |
the never ending story .-) https://docs.python.org/3/glossary.html#term-universal-newlines
I think it is pandoc - back home i will test that. I have a running WIN and Linux env. |
I suspect pandoc is the culprit. It looks like there is a flag that can be set to force line enders It looks like everything else is rendering fine, but I have to wonder why this isn't messing with more things. |
I set up a conda environment in Windows Subsystem for Linux and was able to get the centered equations to run properly. It is most definitely the Windows issue. I do suspect that /n/r characters are occurring via pandoc in the intermediate rst form. (Unfortunately, I cannot get parallel building to work on WSL; this along with WSL's hindered disk IO makes the sphinx build slow... An eventual fix to this would be awesome :D) Edit: googling "WSL waiting for workers" brings up a bunch of Marxist info pages haha :) |
I tried using You can try #160 to see if it works for you. However, this doesn't work for Python 2, because it doesn't use UTF-8 by default and there is no I could drop Python 2 support, but I'm not sure if I should do that already. Is it possible to get |
This flag is available in pandoc. Not sure if it is exposed in the python API:
|
Thanks @meowklaski, that sounds promising! Looks like this option was added in version 2.0. I've created #161, but I have no idea if that actually works. Can somebody please test it with BTW, there isn't really a Python API for |
This did the trick! Verified on Windows with pandoc 2.1 The \begin statement has to have a blank line before it for the math to be rendered correctly. |
@rsokl Thanks for testing! |
Thanks @rsokl, I'm glad that you like Thanks for sharing your notebooks about Python, it's always nice to see I was wondering why you don't seem to be using code cells in your notebooks? BTW, I've just made a new release, now the pandoc/Windows issue should be gone. |
Stylistically, I like how the markdown code-blocks mesh with the surrounding text more. It has a more integrated feel to it. The code cells and their numbering make the text feel a bit too divided, visually. I do make use of them when specifically referring to IPython console and Jupyter Notebook commands This is a funny coincidence. In the summers, I teach a course for high school kids to learn about programming and some cutting edge applications - we do a week on audio processing (which is not my specialty), and I have the kids code up their own "shazaam-ish" music recognition program. I'll definitely make use of your audio resources! I'm actually making that Learning Python website in part for these students. It might overlap with some of the basic review material that you're doing. |
@rsokl OK, it's of course fine to use to use Python console-like code listings. However, there are a few things I'd like to point out:
|
Thanks for the useful pointers! :) It actually had occurred to me today that the commenting style that I was using in the code blocks wouldn't accommodate easy copying and pasting for the reader. It's unfortunate that I'd need to clutter those leading comments with the I think what I will do is make note of my commenting style to the reader upfront, and indicate that those portions of the code are not to be copied/pasted. Most of my text have enough formatted elements that getting to see them render within the notebook is a nice way for me to size up what the reader will be seeing in html form, which is why I steer away from pure-rst files. The pycon-annotated code blocks don't appear to render any differently than do the python-annotated ones, once the html is rendered. |
I just want to emphasize that there are errors (typos) in your code examples, and it would be really simple to spot them using the Sphinx
For that, I highly recommend
Oh, that's interesting. But just for the record, on Gihub comments there is still a difference ... |
Regarding copy-pasting: |
@mgeier I will definitely make it a priority to make use of It may seem silly, but working with notebooks (with a spellcheck plugin) is really much more convenient than is writing .rst files and checking the output with sphinx_build. Given the amount of content that I'm dealing with, having the convenient interface of switching between markdown and code cells ultimately nets me a huge amount of time. What I will likely end up doing is writing a simple tool that extracts the code blocks from my notebooks, writes them to corresponding .rst files, and then runs I'll check out Thank you for all this great direction. I'm hoping that I can produce a really high quality resource for people to learn Python; it'd be great if you had any other feedback |
I just realized that in the most recent version of ipython and jupyter notebook, that my format of code blocks do actually copy/paste nicely. E.g. the following code runs fine when pasted directly in both an ipython console and a notebook # assign the variable `x` to the integer 1
>>> x = 1
# checking the type of `x`
>>> type(x)
int
# verifying that `x` is an integer-type object
>>> isinstance(x, int)
True Previously, the leading comment caused a syntax error, so that's good news :) |
That's great! One last question: are the source notebooks available somewhere? |
@mgeier sorry for such a late response! I am hosting my repo privately - some content (graded assignments) I do not want to be available to students. I'd be happy to add you to the repo, if you'd like. The content is now hosted at https://www.pythonlikeyoumeanit.com/ Unfortunately, I found pytest.doctest to be a massive pain, mainly due to this bug. Also it gets certain trivial things wrong. For example, it flags the following as incorrect >>> type(1)
int That being said, I am very glad to have combed through the code blocks; it pointed me to several mistakes. |
Are there assignments?
No thanks, I'd much prefer if the whole thing were public.
Because it is incorrect? >>> type(1)
<class 'int'> |
Oh that's so weird. I never knew the IPython hooked into anything different for printing the console-output . It looks like it formats several things more cleanly:
I really hope
I'm definitely open to making the repo public. My online class just went live, and there have been many pressing things that I've had to deal with, so I was just playing things on the safe side. There really isn't anything to play with. These notebooks are almost all pure-markdown. Their sole purpose is to map to easy-to-follow/read web pages. Down the road, I might add work sheets and/or demos, in which case it would be nice to supply binder links. |
@rsokl You were talking about the https://networkx.github.io/documentation/latest/tutorial.html It seems to be using this: https://github.com/networkx/networkx/blob/master/doc/_static/copybutton.js And now I know where I saw it originally: in the official Python docs! |
@mgeier Thank you so much for bringing this to my attention! I will definitely be able to make good use of this in my site. Greatly appreciated! 😁 |
When trying to reproduce the centered equation from your documentation (using the latest version of
nbsphinx
from pypi):I find that the centered equation does not render properly:
I used the exact content of your notebook cell:
The text was updated successfully, but these errors were encountered: