Comments (12)
Thanks @bnaul . Also pinging @willingc, who works quite a bit on our own docs.
from nbsphinx.
Thanks @takluyver. @bnaul If you have a sample notebook, I would be happy to look at it. In general, there are pros and cons with different conversion workflows. FWIW, we've been using recommonmark
and nbsphinx
with good success that past few months on Jupyter projects. Also pinging @mgeier for input.
from nbsphinx.
@bnaul Another thing to look at is the exact versions that you are using in Sphinx, nbsphinx, and recommonmark. Certain combinations have more issues than others.
from nbsphinx.
To clarify, Fernando and I were just talking to Brett in person, and asked him to open this issue. While there might be workarounds for any specific case, that's a game of whack-a-mole: the non-code parts of notebooks are markdown, so translating to rst before loading notebooks into Sphinx always runs the risk of messing something up.
We suggested that maybe nbsphinx should depend on recommonmark or something similar, and cut the rst stage out of the loading process. I may be able to spare some time to look into this, though I don't know much (anything?) about the Sphinx API.
from nbsphinx.
Ahh...thanks for the context @takluyver. I would be happy to have a direct conversion from markdown in
notebook cells to HTML. The less conversions the better.
from nbsphinx.
Thanks @bnaul for bringing this up and thanks all for the comments!
Quite some time ago, I read that nested inline markup is not possible with docutils. I thought that this is a general limitation of docutils, but as it turns out now, that it is actually only a limitation of the reST parser!
A few weeks ago, @takluyver already mentioned the possibility of using recommonmark: jupyter/nbconvert#222 (comment). At that time I thought this would only be an implementation detail, but as it turns out, using recommonmark may potentially overcome some fundamental problems found in the current implementation.
I started with the intermediate rst
stage because it was the only way I could get started at all, but from my standpoint today, I think it would be better to drop the intermediate rst
and parse directly into the docutils document structure.
However, experience may show that switching to recommonmark brings more damage than good, but we'll have to try it to find out if that's true.
This will be a lot of work, @takluyver if you are eager to tackle that, feel free to do so.
If not, I can give it a try, but it will take a considerable amount of time ...
from nbsphinx.
I wouldn't quite say I'm eager, but I will look into it ;-)
from nbsphinx.
I had another look at the title of this Issue: "Allow conversion via markdown instead of RST" ...
@bnaul If that's literally what you mean, I'm strongly against it!
I'd rather want something like "Convert directly to docutils without intermediate RST".
In this case, nbsphinx
would walk the notebook cells, "manually" convert code cells to the docutils representation and use a library like recommonmark to convert Markdown cells.
@takluyver Was that how you understood it?
from nbsphinx.
@mgeier sure, that's a good description; the main issue in my mind is just allowing markdown to be rendered as faithfully as possible.
from nbsphinx.
Yep, loading it as directly as possible into the docutils representation would clearly be ideal.
from nbsphinx.
I noticed today that including HTML links (<a href="url">txt</a>
) in Markdown fails to render the link as Pandoc doesn't preserve HTML links when converting Markdown to RST. This could be considered a bug in Pandoc, but it's also a +1 in favor of this issue :)
from nbsphinx.
Getting tables and math to work might be hard.
There's at least a rudimentary math extension for recommonmark, but I didn't find any documentation about tables.
It's probably less nerve-wrecking to write a new (and extensible) CommonMark parser than trying to fumble all this into recommonmark ...
from nbsphinx.
Related Issues (20)
- Download buttons/links HOT 7
- Non working internal links for manually added anchors in 0.9.2 HOT 4
- Unable to create gallery with notebooks out of the doc tree with nblinkgallery HOT 1
- Not compatible with the latest `pandoc` version HOT 2
- Failure on multi-line maths with leading indentation
- Scroll long output HOT 1
- 0.9.2: documentation build fails HOT 1
- `DataFrame` with long column labels is not rendered correctly with the `pydata` theme HOT 1
- What's the best way to add support for sphinx directives in markdown cells? HOT 3
- xelatex support HOT 3
- How to link to a notebook from another file ? HOT 2
- WARNING: toctree glob pattern '*.ipynb' didn't match any documents HOT 1
- Math rending issue after converting the doc HOT 1
- nbsphinx PDF don't render Ploty Plot HOT 2
- Backslashes in markdown cells are sometimes incorrectly interpreted as inline TeX HOT 4
- Error on cells using tqdm
- Error on cells using progress bar (tqdm) HOT 7
- Avoid sphinx searching on output cells HOT 10
- Custom nbsphinx-gallery.css does not take into account - sphinx 7.2.6 HOT 7
- drop dependency to pandoc ? HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from nbsphinx.