{"action":"created","issue":{"url":"https://api.github.com/repos/JuliaLang/julia/issues/13047","labels_url":"https://api.github.com/repos/JuliaLang/julia/issues/13047/labels{/name}","comments_url":"https://api.github.com/repos/JuliaLang/julia/issues/13047/comments","events_url":"https://api.github.com/repos/JuliaLang/julia/issues/13047/events","html_url":"https://github.com/JuliaLang/julia/issues/13047","id":105709263,"number":13047,"title":"Converting the standard library to 100% Markdown","user":{"login":"mbauman","id":154641,"avatar_url":"https://avatars.githubusercontent.com/u/154641?v=3","gravatar_id":"","url":"https://api.github.com/users/mbauman","html_url":"https://github.com/mbauman","followers_url":"https://api.github.com/users/mbauman/followers","following_url":"https://api.github.com/users/mbauman/following{/other_user}","gists_url":"https://api.github.com/users/mbauman/gists{/gist_id}","starred_url":"https://api.github.com/users/mbauman/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mbauman/subscriptions","organizations_url":"https://api.github.com/users/mbauman/orgs","repos_url":"https://api.github.com/users/mbauman/repos","events_url":"https://api.github.com/users/mbauman/events{/privacy}","received_events_url":"https://api.github.com/users/mbauman/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/JuliaLang/julia/labels/doc","name":"doc","color":"02d7e1"},{"url":"https://api.github.com/repos/JuliaLang/julia/labels/docsystem","name":"docsystem","color":"d4c5f9"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":3,"created_at":"2015-09-10T00:29:59Z","updated_at":"2015-09-10T17:30:31Z","closed_at":null,"body":"There are currently 332 docstrings that haven't made the conversion to Markdown.  While they still display nicely in the online manual, they are simply output as plaintext with RST markup at the terminal.  Since the end goal is to have the entire manual as markdown (#12573), we will need to figure out ways of spelling the features we want in Markdown sooner or later.  Here are the syntaxes that are currently used, roughly sorted by frequency of use:\r\n\r\n* [ ] Function references (``:func:`foo` `` and sometimes ``:ref:`~ operator <~>` `` or ``:func:`f(x+y) <f>` ``)\r\n* [ ] Object references (`` :obj:`Bar` `` and sometimes `` :class:`Quux` `` or ``:const:`BAZ` ``)\r\n* [ ] Error references (`` :exc:`ErrorException` ``)\r\n* [ ] Links to sections in the manual (``:ref:`Link name <man-link-anchor>` `` or auto-populated with anchor title by ``:ref:`man-link-anchor` ``)\r\n* [ ] Doctests (#13045)\r\n* [ ] Inline latex (``:math:`\\latex` ``) — I think ``inline $x^2$`` is currently supported (72 uses, very few blocked by other syntaxes).\r\n* [ ] Superscripts (``:sup:`T` ``) — could use unicode since its use is limited to `Aᵀ` and `Bᴴ` (18 uses, none blocked by other syntaxes).\r\n* [ ] Bullet lists (#13046)\r\n* [ ] Notes (`.. note::`) (example: [gcdx](http://docs.julialang.org/en/release-0.3/stdlib/math/#Base.gcdx))\r\n* [ ] Citations, sometimes with inline references to things cited elsewhere (`logm`, `pinv`, `sqrtm`, `expm`, `bkfact`, `qrfact`, `full`)\r\n* [ ] Tables (MultiMarkdown has a possible solution)\r\n* [ ] Literal inline code blocks (`` :literal:`has\\` in it` ``)?\r\n\r\nWe probably don't really need to preserve all of Python's different ways of referencing functions/objects/classes/constants/exceptions/etc.  But that is far and away the biggest reason why most RST blocks haven't been converted.  If we can figure out a way to do references, we'll be 90% of the way there.\r\n\r\nNote that if one method's docstring failed to auto-convert to markdown, none of the functions methods were converted to markdown.  So when addressing one of the items above, search to see if addressing the docstring of one method frees all the other methods, too."},"comment":{"url":"https://api.github.com/repos/JuliaLang/julia/issues/comments/139319049","html_url":"https://github.com/JuliaLang/julia/issues/13047#issuecomment-139319049","issue_url":"https://api.github.com/repos/JuliaLang/julia/issues/13047","id":139319049,"user":{"login":"mbauman","id":154641,"avatar_url":"https://avatars.githubusercontent.com/u/154641?v=3","gravatar_id":"","url":"https://api.github.com/users/mbauman","html_url":"https://github.com/mbauman","followers_url":"https://api.github.com/users/mbauman/followers","following_url":"https://api.github.com/users/mbauman/following{/other_user}","gists_url":"https://api.github.com/users/mbauman/gists{/gist_id}","starred_url":"https://api.github.com/users/mbauman/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mbauman/subscriptions","organizations_url":"https://api.github.com/users/mbauman/orgs","repos_url":"https://api.github.com/users/mbauman/repos","events_url":"https://api.github.com/users/mbauman/events{/privacy}","received_events_url":"https://api.github.com/users/mbauman/received_events","type":"User","site_admin":false},"created_at":"2015-09-10T17:30:31Z","updated_at":"2015-09-10T17:30:31Z","body":"Perhaps the solution for function references is to use `$(link(foo))`.  For now, it could just splice in `[foo()](#foo)`, which would become ``:ref:`foo() <foo>` ``, but it would allow us to use multiple dispatch to format functions/objects/types/etc differently in the future without mucking with the docs again."}}