Creating Official .NET Core Docs

[richlander]

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.

• ASP.NET Docs Repo - https://github.com/aspnet/docs
• ASP.NET Hosted RTDs - http://docs.asp.net

This is a follow-on from: https://github.com/dotnet/coreclr/issues/939#issuecomment-99726811

[richlander]

@danroth27 Can you clarify the creation of a C#/IL RST domain (referenced in #4223)?

[tony]

Very interested in that.

FYI, not sure if this is stepping on toes / already a different approach is underway:

Here is a checklist of sphinx things to consider:

reStructuredText vs MD in repo

(mentioned above by @richlander https://github.com/dotnet/coreclr/issues/939#issuecomment-99741196)

You could use both.

Any issues / confusion anyone had with reST / sphinx I could help square away here?

One 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.

It's true the peculiarities between MD / reST could throw people off. So I don't object to using markdown in repo.

The C#/MSIL domain

(mentioned above by @richlander)

To 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.

Generate API Docs from code

After 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.

Do 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-like front-end that automatically lays out the docs.

sphinx.ext.intersphinx and Interlinking

The 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.

In addition, you can link throughout other docs in the sphinx project, and also across other sphinx projects.

That means that ASP.net's sphinx can easily link into CoreCLR's sphinx, and vise-versa.

Docs theme

ReadTheDocs 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.

LaTeX (PDF) theme

The 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.

Languages

Any intent to support docs across languages / start a translation project? Sphinx does have some internationalization support, but we'd need contributors.

ReadTheDocs let you switch between languages (http://tmuxp.readthedocs.org/en/latest/, http://tmuxp.readthedocs.org/zh_CN/latest/) on bottom left corner.

[danroth27]

@richlander @ericholscher Yup, we are working with the Read the Docs folks on developing a .NET Sphinx domain.

[ericholscher]

Yep. Happy to answer questions if folks have them. Also a note, that we are adding Markdown support (CommonMark to be specific), so that you can have RST & Markdown in the same project. All the "Sphinxy" features will be RST-only for now, but you could have sets of docs that were Markdown, and then add them into the toctree/etc in RST.

[tony]

@ericholscher small world Eric. :p

What about the sphinx domain?

Re: CommonMark <-> Sphinx/RTD, Which repo is this underway at? Will it be possible to .. include:: markdown docs from reST pages?

[richlander]

There is a separate effort on this now. We can close this issue.

[richlander]

Closed. Thanks.

---

From: tzwlai [email protected]
Sent: Tuesday, October 27, 2015 3:43:01 PM
To: dotnet/coreclr
Cc: Richard Lander
Subject: Re: [coreclr] Creating Official .NET Core Docs (#948)

Assigned #948https://na01.safelinks.protection.outlook.com/?url=https%3a%2f%2fgithub.com%2fdotnet%2fcoreclr%2fissues%2f948&data=01%7c01%7crlander%40microsoft.com%7c1b703019422e4af5f15408d2df1ff893%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=0dRu4RCNtZKWbfMj4B1zm%2fBrC3%2bTe2K3kbUYdJsZx6c%3d to @richlanderhttps://na01.safelinks.protection.outlook.com/?url=https%3a%2f%2fgithub.com%2frichlander&data=01%7c01%7crlander%40microsoft.com%7c1b703019422e4af5f15408d2df1ff893%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=tL9aUgWTSpIsEjbkxVY7JojFYrhBUhbSBHdhzZsjhz0%3d.

Reply to this email directly or view it on GitHubhttps://na01.safelinks.protection.outlook.com/?url=https%3a%2f%2fgithub.com%2fdotnet%2fcoreclr%2fissues%2f948%23event-447405215&data=01%7c01%7crlander%40microsoft.com%7c1b703019422e4af5f15408d2df1ff893%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=dMJqYl%2fbONoWnNQJCR0zNkT4agfVbgbHOBvUALSyzyQ%3d.