{"action":"created","issue":{"url":"https://api.github.com/repos/rust-lang/rust/issues/29474","labels_url":"https://api.github.com/repos/rust-lang/rust/issues/29474/labels{/name}","comments_url":"https://api.github.com/repos/rust-lang/rust/issues/29474/comments","events_url":"https://api.github.com/repos/rust-lang/rust/issues/29474/events","html_url":"https://github.com/rust-lang/rust/issues/29474","id":114278131,"number":29474,"title":"Switch rustdoc away from Markdown","user":{"login":"flying-sheep","id":291575,"avatar_url":"https://avatars.githubusercontent.com/u/291575?v=3","gravatar_id":"","url":"https://api.github.com/users/flying-sheep","html_url":"https://github.com/flying-sheep","followers_url":"https://api.github.com/users/flying-sheep/followers","following_url":"https://api.github.com/users/flying-sheep/following{/other_user}","gists_url":"https://api.github.com/users/flying-sheep/gists{/gist_id}","starred_url":"https://api.github.com/users/flying-sheep/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/flying-sheep/subscriptions","organizations_url":"https://api.github.com/users/flying-sheep/orgs","repos_url":"https://api.github.com/users/flying-sheep/repos","events_url":"https://api.github.com/users/flying-sheep/events{/privacy}","received_events_url":"https://api.github.com/users/flying-sheep/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":10,"created_at":"2015-10-30T14:15:15Z","updated_at":"2015-10-31T15:50:02Z","closed_at":"2015-10-30T16:19:17Z","body":"Technical documentation needs more features than Markdown has.\r\n\r\nE.g. the ability to easily (and prettily) link to classes and functions from text is invaluable for usability.\r\n\r\nWhile Markdown is well-known and has good syntax for inline links, those features lend themselves rather to forums and the like than for large documents with a high amount of structure and internal crossreferences.\r\n\r\nlooking at pages like [Path](https://doc.rust-lang.org/std/path/struct.Path.html), i’m sad about the lack of visually distinct and link-wielding references in the text.\r\n\r\nI think [Sphinx](http://sphinx-doc.org/tutorial.html) is as close to perfection as it can get. Its extensible roles and directives, as well as advanced features based on them like intersphinx links are perfect for what a programming language documentation needs.\r\n\r\ninstead of having a generic `str` in that text, we could e.g. have a [<samp>str</samp>](https://doc.rust-lang.org/std/primitive.str.html) in there with only a few characters added in the documentation markup.\r\n\r\nSo I propose to rebase rustdoc onto sphinx, or (although that’s probably too much work) a intersphinx-compatible rST implementation"},"comment":{"url":"https://api.github.com/repos/rust-lang/rust/issues/comments/152744770","html_url":"https://github.com/rust-lang/rust/issues/29474#issuecomment-152744770","issue_url":"https://api.github.com/repos/rust-lang/rust/issues/29474","id":152744770,"user":{"login":"flying-sheep","id":291575,"avatar_url":"https://avatars.githubusercontent.com/u/291575?v=3","gravatar_id":"","url":"https://api.github.com/users/flying-sheep","html_url":"https://github.com/flying-sheep","followers_url":"https://api.github.com/users/flying-sheep/followers","following_url":"https://api.github.com/users/flying-sheep/following{/other_user}","gists_url":"https://api.github.com/users/flying-sheep/gists{/gist_id}","starred_url":"https://api.github.com/users/flying-sheep/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/flying-sheep/subscriptions","organizations_url":"https://api.github.com/users/flying-sheep/orgs","repos_url":"https://api.github.com/users/flying-sheep/repos","events_url":"https://api.github.com/users/flying-sheep/events{/privacy}","received_events_url":"https://api.github.com/users/flying-sheep/received_events","type":"User","site_admin":false},"created_at":"2015-10-31T15:50:02Z","updated_at":"2015-10-31T15:50:02Z","body":"i’m still questioning the value of people being familiar with it (you really can learn the whole thing in if not 5 then ~12 minutes, just like the equivalent subset of rST)\r\n\r\nsorry to hear that about rustdoc…"}}