Reworked documentation to use DocFX

[richorama]

Please browse here to see the working site: http://richorama.github.io/orleans/

The readme.md contains instructions on how to build the docs.

[sergeybykov]

Looks totally awesome! The search box is what we were missing all alone.

Do I understand the editing process correctly, that it involves three steps now: 1) make edits to .md files; 2) run docfx src\docfx.json to generate .html files; 3) commit updated .md and .html files?

[jdom]

I love that this would also enable to generate documentation of our APIs from source code, and you can jump right into the source code in github from it.
For our current markdown docs, they look awesome! we'd need to figure out how to automate this though, as we can't expect docs PRs to include both the md and the html files from a local run of the docfx tool.

[shayhatsor]

That's just great! Finally !!! @richorama, are there any pitfalls or gotchas you've encountered ?

[galvesribeiro]

So basically, can we (/me looking to @sergeybykov and .Net Foundation) get a domain and put on top of it? These changes shouldn't break the whole ranking on searches anymore

[richorama]

@galvesribeiro yes, you could buy something like orleans.io and point it at the docs.

[galvesribeiro]

Yes I can buy it no problem, but I mean, it would be good if the team and/or the foundation keep its administration. (just in case I decide to start a rock band and not work with tech anymore 🎸 😄 )

note: orleans.io is unnavailable :(

[sergeybykov]

I checked. Looks like the issue with links pointing to forks is resolved now.

Let's merge this as a first step, so that we immediately benefit from the better usable docs. We can move to a separate repo as a separate follow-up effort.

@richorama Could you rebase this please. There's a minor conflict with the recent updates to docs.

[richorama]

@sergeybykov synced!

[richorama]

merged again!

[jdom]

was this file removed on purpose or a merge conflict? Because I see the .md file is gone, but there is html documentation generated for this.

[jdom]

The diff does not open entirely in github, so I'll add a few loose comments here (as I'm only seeing them when I review the branch locally)

[jdom]

In the combined log, I see several added links to https://github.com/richorama/orleans/blob/gh-pages. Could they have been generated before you updated DocFX to point to dotnet/orleans? Or maybe the links in the source where just incorrect before and now the html is generated incorrectly too?

[jdom]

manifest.json contains a local path called C:/Users/Richard/

[jdom]

Oh, wow! I just finished reviewing locally, and I'm really impressed by the level of care you took to fix links, headers, etc. This is a tremendous contribution not just by the result, but by the effort required.
Thanks a lot.
Other than those minor comments, the rest of the diff looks outstanding.

[jdom]

I tried building with the latest docfx (2.4.0.0), and I no longer see the improve this doc button. Do you know why that is?

[richorama]

@jdom

• The 'improve this doc' link has moved to the top of the menu on the right hand side (I didn't see it there either, until I looked at the commit on the docfx repo). We customise the template to put a more obvious button in, but I'm wary of doing too much customisation, as I think we'd rather be on the defaults.
• The manifest.json is generated by docfx. I'm not sure of it's purpose, but it doesn't seem to be used. I wonder if we should exclude it from the repo?
• There were a few orphaned HTML pages which I removed in f30684e, these contained 'improve this doc' links still pointing to my fork.

[jdom]

• I built locally, and still can't find the Improve this doc button (or an alternative for it). Nevertheless, I think we can fix this after I merge, as I don't want you to have to resolve merge conflicts once again.
• Not sure about the manifest.json, it looks like it might be safe to exclude. I did not see it in the gitignore file for core-docs repo, nor I see it committed either, maybe I'm looking at the wrong repo?

[jdom]

Wiiii, merged! The documentation is now live at http://dotnet.github.io/orleans/ !!!!
Thanks a lot @richorama, this looks so much nicer

[sergeybykov]

Thank you so much, @richorama! The docs look much more professional now.

As someone said, the most important contribution one can make to an OSS project is by improving its documentation. :-)

[shayhatsor]

WOW! @sergeybykov, I can't believe it, I was actually just about to write that this contribution is one of the most important ones 😄

[galvesribeiro]

Yay! Great work @richorama! 💃

[gabikliot]

I think some of the presentations from https://github.com/dotnet/orleans/tree/gh-pages/Presentations got lost during the migration. I now only see one file there, but there used to be more. For example, it had http://dotnet.github.io/orleans/Presentations/Balancing Techniques in Orleans.pptx

[sergeybykov]

I opened OrleansContrib/meetups#13 last week for the same issue.

[richorama]

@sergeybykov @gabikliot I'll get to it tomorrow :¬)