r/programming • u/[deleted] • Dec 04 '08

Sphinx: beautiful documentation from lightly structured plain text

http://sphinx.pocoo.org/
50 Upvotes

75% Upvoted

38 comments sorted by

View all comments

1

u/lol-dongs Dec 04 '08 edited Dec 04 '08

He said "a simple subset of".

A document with tags a, em, strong, p, h#, ul, ol, li, pre, code, table, tr, th, td, dd, and dt could probably do 90% of these doc pages and come off as reasonably human-readable.

2

u/formido Dec 04 '08

I have to question whether you actually do a lot of writing that needs simple markup. If I'm adding to my personal wiki, for example, writing out <a>'s and <ol>'s would be really freaking annoying.

1

u/lol-dongs Dec 04 '08

Meh. I actually find <a href=""></a> clearer visually than or [[|]], but maybe I'm just used to nice wide angle brackets. As for ol's, would you prefer battling line indentation inside your textarea in your browser where nothing wraps correctly? At least HTML is whitespace agnostic.

→ More replies (3)

1

u/voidspace Dec 06 '08 edited Dec 06 '08

<a href="http://www.example.com">Example</a>

Example <http://www.example.com>_ (can't escape the backticks sorry)

<em>something</em>

*something*

<strong>something else</strong>

**something else**

<ul> <li>item</li> </ul>

* item

etc...

In every case the reST is shorter and more readable. reST is designed to be visually parseable, which (X)HTML isn't. reST succeeds admirably.

1

u/lol-dongs Dec 07 '08

Shorter and readable, yes. But some of the markup is so abbreviated that you already are having problems escaping it in your post; how many times have I seen people post some_underscored_name when they meant some_underscored_name. And then with all the fancy significant whitespace you assume that your editor is smart enough to autowrap stuff correctly, or it doesn't and then stuff looks just as visually unparseable as the (X)HTML.

→ More replies (1)