[scrollaway]

No offense and all (I'm a huge python guy) but... why? RST is a pretty god damn awful format. Markdown lacks a proper standard but that's really the only problem with it... I wish the python community would just adopt Markdown for good and stop trying so hard with rst.

[williamstein]

I've wondered about the same question, and I also personally greatly prefer markdown. I got into Python in 2002, and my recollection is that RST was introduced a few years before Markdown. Thus RST was more mature than Markdown at the time when Python documentation was a disaster zone and people were looking around for technology on which to build Sphinx. So I think RST versus Markdown for Python is more or less a "historical accident"; by now, there's a massive amount of documentation in RST, and it's too hard to switch everybody over. This situation reminds me somewhat of how Python uses Mercurial instead Git (see [1]); many years ago it was unclear whether Mercurial or Git would "win", and in fact many people (at least myself included, with SageMath!) thought incorrectly that Mercurial would win. Hindsight is 20/20, and fixing making the wrong bet on which technology will win can be extremely painful (at least it was very hard for us to switch SageMath from Mercurial to Git).

[1] https://docs.python.org/devguide/faq.html#where-can-i-learn-...

[scrollaway]

Yeah you're absolutely right. RST was great when Markdown wasn't around, but Markdown is just better.

It's a bit of a toughie, the python community doesn't have much to deal with Markdown itself. pypi expects rst etc. There's also very few tools available in general, which is a huge shame.

Part of this is due to different Markdown "flavours". At this point though, Github being the largest provider of Markdown, a safe bet would be to standardize on Github's flavour and call it a day.

[williamstein]

"a safe bet would be to standardize on Github's flavour and call it a day." - yes, definitely. That's precisely what I'm doing in SageMathCloud.

[dragonwriter]

> I got into Python in 2002, and my recollection is that RST was introduced a few years before Markdown.

That's true: According to Wikipedia RST is from 2002 (so is AsciiDoc), Markdown from 2004. Perhaps also important though is that RST was introduced as a direct successor to StructuredText, which apparently, had some currency in the Python community previously.

[halosghost]

Actually, I completely disagree. Rst can do things that markdown will never be able to do (at least, not any of the common dialects). E.g., you can create your own directives to do special formatting however you'd like. You also have a ton more functionality built-in (e.g., a directive for LaTeX-style math) that is also incredibly uncommon in markdown.

Furthermore, the document structure in rst is far more powerful (e.g., you choose your heading conventions).

As it turns out, I am not actually a huge fan of python (and there are plenty of problems with rst), but in the comparison between mdown and rst, the only argument I actually see in favor of mdown is that it's more commonly used (though the fact that commonmark has yet to completely take over actually mitigates that a fair bit).

[scrollaway]

It doesn't matter how much you can do with RST if the syntax is horrible.

The syntax is horrible.

[halosghost]

I can see how you might feel that way about some of it. But I actually do not really find that to generally be the case. And plenty of it is far nicer than Mdown.

However, this is jumping into completely subjective territory; you, of course, do not have to like rst, just as I do not have to like mdown. So, I will stick with my original sentiment of wishing these services would support the thing I like :)

[scrollaway]

My syntax comment was a bit abstract, apologies about this. I'm referring to RST's strictness and how painful it is to deal with, for example, something as simple as links. I don't really care which way you bold or italicize words, really...

[halosghost]

Yeah, this just feels subjective (which isn't bad, just not terribly helpful). I find the fine-grained control gives me more power (which I prefer to something that's simpler but less powerful).

Rst feels like a happy medium between mdown and LaTeX for me, which is actually very much how I use it. I use it in situations where I would have used LaTeX in the past (instances where mdown surely wouldn't cut it). Of course, there are some times (e.g., tables, figures and bibliographies) where LaTeX is the only sensible option, but for anything simpler, I'd still prefer the power that Rst gives me.

Additionally, I actually really like most of how Rst does URLs. It is definitely less simple than mdown, but it's so much more powerful and generalized.

[jumpwah]

> Markdown lacks a proper standard

http://commonmark.org/. Of course, you might already know about this, and just be playing the https://xkcd.com/927/ card.

On that topic, does anyone know what flavour of markdown is being used here (in fiddle.md)?

[pimpl]

We use marked - https://github.com/chjj/marked - with some slight modifications.

[jumpwah]

Cool. Thanks for the clarification.

[ryannevius]

And here I thought I was alone on this. Glad to see that I'm not the only one who things RST is terrible.