[Docutils-users] Swift using reStructuredText

[Tony Narlock]

Greetings Docutils Users,

I'm pleased to let you know, Apple's Swift project joins CoreCLR, LLVM,
CMake and other projects to use reStructuredText for their documentation.

https://github.com/apple/swift/tree/master/docs

Take note of how the project uses CMakeLists.txt for creating the sphinx
Makefile: https://github.com/apple/swift/blob/master/docs/CMakeLists.txt

[Tony Narlock]

Unfortunately, it seems they will be moving to markdown for unspecified
reasons. Apparently they already made up their mind internally.

https://lists.swift.org/pipermail/swift-dev/2015-December/000047.html
https://github.com/apple/swift/pull/246

A bit more detail was added later:

"(Why GitHub-Flavored Markdown? Because most likely the most common way to
view them will be on GitHub. If we can also get Kramdown compatibility
that's great, because that's what our website uses, but that's just a
bonus.)"

Source: https://github.com/apple/swift/pull/246#issuecomment-162233091

It's hard to beat the feature set of sphinx, but there are some nice
systems out there popping up we can learn from.

Post by Tony Narlock
Greetings Docutils Users,
I'm pleased to let you know, Apple's Swift project joins CoreCLR, LLVM,
CMake and other projects to use reStructuredText for their documentation.
https://github.com/apple/swift/tree/master/docs
Take note of how the project uses CMakeLists.txt for creating the sphinx
Makefile: https://github.com/apple/swift/blob/master/docs/CMakeLists.txt

[Philipp A.]

that’s idiotic. they remove all the semantic information and convert their
perfectly fine directives into inconistent 
stuff.

**note**
...

or

Note: ...

from being a “note”, this now became (maybe bold) text inside a blockquote.
who’s being quoted here? Why throw away information that can be used for
clarity?

goddammit. that sounds like some kind of clueless corporate decision:
“Github is hip these days so let’s host our docs on Github, no matter the
consequences”

Unfortunately, it seems they will be moving to markdown for unspecified
reasons. Apparently they already made up their mind internally.
https://lists.swift.org/pipermail/swift-dev/2015-December/000047.html
https://github.com/apple/swift/pull/246
"(Why GitHub-Flavored Markdown? Because most likely the most common way to
view them will be on GitHub. If we can also get Kramdown compatibility
that's great, because that's what our website uses, but that's just a
bonus.)"
Source: https://github.com/apple/swift/pull/246#issuecomment-162233091
It's hard to beat the feature set of sphinx, but there are some nice
systems out there popping up we can learn from.

Post by Tony Narlock
Greetings Docutils Users,
I'm pleased to let you know, Apple's Swift project joins CoreCLR, LLVM,
CMake and other projects to use reStructuredText for their documentation.
https://github.com/apple/swift/tree/master/docs
Take note of how the project uses CMakeLists.txt for creating the sphinx
Makefile: https://github.com/apple/swift/blob/master/docs/CMakeLists.txt

------------------------------------------------------------------------------
Go from Idea to Many App Stores Faster with Intel(R) XDK
Give your users amazing mobile app experiences with Intel(R) XDK.
Use one codebase in this all-in-one HTML5 development environment.
Design, debug & build mobile apps & 2D/3D high-impact games for multiple
OSs.
http://pubads.g.doubleclick.net/gampad/clk?id=254741911&iu=/4140
_______________________________________________
Docutils-users mailing list
https://lists.sourceforge.net/lists/listinfo/docutils-users
Please use "Reply All" to reply to the list.

[Zooko Wilcox-OHearn]

“Github is hip these days so let’s host our docs on Github, no matter the
consequences”

Github renders restructuredText docs for you.

For example: https://github.com/LeastAuthority/tahoe-lafs/blob/master/docs/quickstart.rst