{"action":"created","issue":{"url":"https://api.github.com/repos/dotnet/coreclr/issues/948","labels_url":"https://api.github.com/repos/dotnet/coreclr/issues/948/labels{/name}","comments_url":"https://api.github.com/repos/dotnet/coreclr/issues/948/comments","events_url":"https://api.github.com/repos/dotnet/coreclr/issues/948/events","html_url":"https://github.com/dotnet/coreclr/issues/948","id":73866810,"number":948,"title":"Creating Official .NET Core Docs","user":{"login":"richlander","id":2608468,"avatar_url":"https://avatars.githubusercontent.com/u/2608468?v=3","gravatar_id":"","url":"https://api.github.com/users/richlander","html_url":"https://github.com/richlander","followers_url":"https://api.github.com/users/richlander/followers","following_url":"https://api.github.com/users/richlander/following{/other_user}","gists_url":"https://api.github.com/users/richlander/gists{/gist_id}","starred_url":"https://api.github.com/users/richlander/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/richlander/subscriptions","organizations_url":"https://api.github.com/users/richlander/orgs","repos_url":"https://api.github.com/users/richlander/repos","events_url":"https://api.github.com/users/richlander/events{/privacy}","received_events_url":"https://api.github.com/users/richlander/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2015-05-07T06:39:39Z","updated_at":"2015-05-07T15:44:05Z","closed_at":null,"body":"The team is looking at using ReStructureText for the official .NET Core docs. There are many questions to answer on that. This is based on the ASP.NET team's decision to also use RST.\r\n\r\n- ASP.NET Docs Repo - https://github.com/aspnet/docs\r\n- ASP.NET Hosted RTDs - http://docs.asp.net\r\n\r\nThis is a follow-on from: https://github.com/dotnet/coreclr/issues/939#issuecomment-99726811"},"comment":{"url":"https://api.github.com/repos/dotnet/coreclr/issues/comments/99916569","html_url":"https://github.com/dotnet/coreclr/issues/948#issuecomment-99916569","issue_url":"https://api.github.com/repos/dotnet/coreclr/issues/948","id":99916569,"user":{"login":"tony","id":26336,"avatar_url":"https://avatars.githubusercontent.com/u/26336?v=3","gravatar_id":"","url":"https://api.github.com/users/tony","html_url":"https://github.com/tony","followers_url":"https://api.github.com/users/tony/followers","following_url":"https://api.github.com/users/tony/following{/other_user}","gists_url":"https://api.github.com/users/tony/gists{/gist_id}","starred_url":"https://api.github.com/users/tony/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tony/subscriptions","organizations_url":"https://api.github.com/users/tony/orgs","repos_url":"https://api.github.com/users/tony/repos","events_url":"https://api.github.com/users/tony/events{/privacy}","received_events_url":"https://api.github.com/users/tony/received_events","type":"User","site_admin":false},"created_at":"2015-05-07T15:44:05Z","updated_at":"2015-05-07T15:44:05Z","body":"Very interested in that.  \r\n\r\nFYI, not sure if this is stepping on toes / already a different approach is underway:\r\n\r\nHere is a checklist of sphinx things to consider:\r\n\r\n### reStructuredText vs MD in repo\r\n\r\n(mentioned above by @richlander https://github.com/dotnet/coreclr/issues/939#issuecomment-99741196)\r\n\r\nYou could use both. \r\n\r\nAny issues / confusion anyone had with reST / sphinx I could help square away here? \r\n\r\nOne thing is if you're viewing an rst doc on GitHub with Sphinx-specific directives, those features won't render in GitHub.  You could always have vanilla-reST pages in GH if you wanted consistency to reST. You could later ``.. include`` those vanilla pages in a sphinx project.\r\n\r\nIt's true the peculiarities between MD / reST could throw people off. So I don't object to using markdown in repo.\r\n\r\n### The C#/MSIL domain \r\n\r\n(mentioned above by @richlander)\r\n\r\nTo be clear, creating a C# domain makes it a lot easier to layout API internals.  It also opens up the ability to link to and between internal code docs.\r\n\r\n### Generate API Docs from code\r\n\r\nAfter a C# domain is finished - work can begin documenting API internals by hand, however, it's probably desirable to scour C++ and CS code and generate API docs for the sphinx domain code.\r\n\r\nDo code internals follow an internal standard? Doxygen? XML? If it's consistent, it's possible to write a scanner to use across all projects. Then we can use an [autodoc](http://sphinx-doc.org/ext/autodoc.html)-like front-end that automatically lays out the docs.\r\n\r\n### [sphinx.ext.intersphinx](http://sphinx-doc.org/latest/ext/intersphinx.html) and Interlinking\r\n\r\nThe benefit of sphinx is it turns everything (documents, sections, API entries, custom targets) into links.  With ReadTheDocs, you can also link to a target/api at a particular version.\r\n\r\n In addition, you can link throughout other docs in the sphinx project, and also across other sphinx projects.\r\n\r\nThat means that ASP.net's sphinx can easily link into CoreCLR's sphinx, and vise-versa.\r\n\r\n### Docs theme\r\n\r\nReadTheDocs uses https://github.com/snide/sphinx_rtd_theme. It handles mobile pretty nicely and has good whitespacing.  If we wanted to theme it a little differently we could fork it to dotnet org and use the customized version in ``conf.py``.\r\n\r\n### LaTeX (PDF) theme\r\n\r\nThe default theme can be ok. But there will probably be a need to tweak things here and there, and eventually customize it entirely.  I could help here too but time is tight.\r\n\r\n### Languages\r\n\r\nAny intent to support docs across languages / start a translation project? Sphinx does have some internationalization support, but we'd need contributors.\r\n\r\nReadTheDocs let you switch between languages (http://tmuxp.readthedocs.org/en/latest/, http://tmuxp.readthedocs.org/zh_CN/latest/)  on bottom left corner."}}