What is Reddit's opinion of Docutils?

From 3.5 billion Reddit comments

You might also want to have a look at reStructuredText. It's got a lot in common with markdown but has more features and has a "directive" syntax to allow extensions. Many of the extensions are well standardized and support things like LaTeX equations.

It's nice that this supports Bitbucket – many things don't – but given that Bitbucket natively handles reStructuredText much better than it does Markdown it would be nice if this did as well so all documentation within the repo can be in the same markup language.

Sphinx outputs LaTeX out of the box. Learning curve is mostly in learning Sphinx flavored RST which isn't hard. Building is very easy:

$ sphinx-quickstart # write your rst $ make latexpdf

Not sure what you mean by scalability, but a lot of very large documents have been written in Sphinx. The Scipy documentation for example

Well, it is not what I would like most:

$ ao3-poster story.rst

(credentials stored in some config file). That would be the ideal, I can settle of course for the file being HTML (or even DOC if anybody cares), but something in this style (again, the ideal would be the metadata picked up from the docinfo part of the document, but I can settle for something else). Writing a text of a long story to one field in a spreadsheet seems a bit crazy to me.

This is what Pandoc was created for. You can write your documents in Markdown and then use Pandoc to convert them to the formats listed. You'll have to do some work tweaking the outputs to your satisfaction, but it can be done.

I will note that if your documents rely heavily on tables, look at using reStructuredText instead of Markdown. Markdown's table support is shit.

1) I would recommend looking into the use of Docstrings in your code, see here for the relevant PEP. Then you can make use of tools such as Docutils to extract the Docstrings from your code, generating nice documentation. I personally find this feature very useful.

You'll probably want to wait for donri's blog, but one (maybe minor) thing about markdown that really leaves a bad taste in my mouth is that it semantically differentiates between 1) zero or one trailing spaces, and 2) two or more trailing spaces, on a line. That's just ridiculous. Trailing space shouldn't affect the semantics of any language, and even if it does, the language should surely at least put the split between "no trailing space" and "some trailing space", not "at most one trailing space" and "multiple trailing spaces"...

I personally use reStructuredText since it's pretty popular in Python world for documentation (though really it's great for a lot of things).

Depending on what you're writing, reStructuredText might be what you want.

http://docutils.sourceforge.net/rst.html

It's syntax is similar to wiki markup and can be converted to LaTeX, HTML, PDF, etc.

Python is documented in it, and it's a real pleasure to use.

(If you want to group together a bunch of separate docs, you might want to check out Sphynx, too)

Markdown

Could also use RestructuredText

Reddit maintains a fork of Sundown to do their markdown rendering: here.

There are a bajillion markdown libraries for PHP, just Google it ...

That's a picture of an old man with a beard on the ceiling of the sistine chapel. Get a real photo of god.

NVM, found one. Here you go. http://docutils.sourceforge.net/docs/user/images/rsp-empty.png

Insert text as you see fit.

Good question.

I haven't used Sphinx, but from the docs `Sphinx uses reStructuredTextas its markup language` - and as I wrote in the blog post I prefer Markdown over rST. This is the main reason for me - if you are ok with rST then Sphinx would probably be a better choice as it has more features, bigger community and "better" license (BSD).

I see there is a bridge to use Markdown with Sphinx https://www.sphinx-doc.org/en/master/usage/markdown.html - this could be interesting.

I did just that for my own blog. One day I wanted to write on a topic and didn't have a blog. I decided to write articles in RST (think markdown but more powerful, more flexible, better) and use rst2html to produce my blog. I didn't want to manage a webserver so I used github.io which works great for me and I know the day I decide to change it'll be painless. It took a wooping 3h to get the site running, most of which was spent on the basic html template and CSS since I'm definitely not a web guy. Push to github and it's done.

A few years later, I love it. It's so small. I never have to write a single line of HTML. Whenever I feel like adding a feature I just code it in. Need RSS? 30 minutes later here's a 100L python script and a new make entry. A tad clunky but it works fine. Want micro-blogging my own way? 30 minutes later here's another 100L script that I use from the command line to publish short skits. With its dedicated RSS too. It's easy to change, easy to fix, builds are fast and there isn't a single line of javascript required.

I don't think that particular engine is likely to fit anyone but me. After all it's as tailored to my workflow and desires as it can get. But it's sooo easyyy to take its basic ideas, have a minimal makefile and base templates and rst2html and get your own blog started fast. I definitely recommend the experience.

You might consider using Sphinx with the reStructuredText markup language, which is similar to Markdown but with a superior feature set for documentation (TOC, pagination, footnotes, citations, templates, etc.). Pandoc can be used to convert (both ways) between .odt and .rst formats, among many others. Both Sphinx and Pandoc are Python-based tools that run on most platforms.

1) Convert existing .odt files to .rst on your workstation;

2) download & edit .rst files (perhaps format & preview w/ Sphinx) on your tablet;

3) upload .rst files to workstation, format and convert final copy to desired format.

RST can transclude a fragment in-line.

A quick websearch seems to show that CommonMark has no standardized transclusion syntax currently, but that it's a big desire from certain quarters.

You'd want to do some light transformation on the TSV/CSV before transcluding, I guess. We'd use make probably, but this hasn't come up so far and we don't normally have to make Git repo content for presentation. However, it's probably inevitable that it will come up, so I'll pay attention to see if any other responses are useful.

The "nested inline markup" limitation of reStructuredText really irks me when it comes to hyperlinking monospace text, and while the FAQ suggests it's "on the to-do list", the author of rST has said elsewhere (and I'm too lazy to dig it up right now) that he's never going to add it, he hates the idea, and everyone else is stupid for wanting it. I really hate his attitude on the issue. Seems like it would be easier to add directives to Markdown, which I believe has a bigger community at this point.

It depends a lot on your workflow, but if you have a tool that can follow successive versions of a document and travel back in time, you can delete or rewrite as much as you want. I use fossil with ReStructuredText but there are other tools that can do something similar.

One approach I've been trying is to output my data in reStructuredText format and then use rst2pdf. This also allowed me to use docutils to output to lots of other formats (doc, html, etc...).

If anyone has the power/knowledge/time to do this, let us use reStructuredText & Sphinx please! (I also love readTheDocs)

Maybe I'll put write a Haskell domain for Sphinx on my things to do in case I'm actually immortal list....

Like what? reStructuredText? I like the link syntax of markdown better, but other than that I'm indifferent. But I guess it has the same problems ("the code is the spec").

I love RST, but I'm wondering what the point of this is. There's an official cheatsheet on the docutils website that's been around since the dawn of time.

Any chance of more lightweight markups in the future? I don't write enough markdown for a full-blown editor to be necessary, but I'd dig that for reStructuredText, especially to write docs if it can handle all the Sphinx markup extensions.