Orleans: Help generating documents from code comments

[JillHeaden]

Has anyone successfully used a document generator like DocFX to create documents from the comments in the Orleans code?
If so, would you be willing to tell me exactly what you did?

[JillHeaden]

My first question is:

In the Orleans Documentation Readme. md - Building the Documentation [https://github.com/dotnet/orleans/tree/gh-pages] section, it says:

To build the documentation you will need a copy of DocFX on your path.

Which path, exactly?

[jason-bragg]

The windows environment path.
https://www.computerhope.com/issues/ch000549.htm

[ReubenBond]

@JillHeaden the easiest way (and probably the recommended way) to accomplish this is by installing DocFx from Chocolatey:

First, install Chocolatey: https://chocolatey.org/install

Then, open a new PowerShell or cmd window and run:

choco install docfx 

(The reason you have to open a new window is that installing Chocolatey updates the system-wide PATH environment variable. Existing windows will still have the old PATH value)

[dandago]

By "generating documents from code comments", do you mean generating class and method reference documentation from XML docs in the code?

If so, I'll just point out (and this is just my own personal opinion) that I've found this kind of thing to be very little use in the past. There are two kinds of documentation I value: usage examples (especially for new users, but also important to progressively learn more advanced concepts) and architectural/conceptual insight (such as most of the current Orleans doc - important as reference material so people can understand in detail how certain things work). These kinds of docs can't be autogenerated.

But I'm not even sure if this is the topic at hand here, so apologies if I'm off track.

[JillHeaden]

@dandago Yes, I did mean generating the class and method documentation, and I agree that usage examples and other non-autogenerated documents are very useful. I wanted to my hands on the autogenerated documents so that I could at least see what the XML is generating.

As of this moment, I still can't get them to work. Jason helped me generate the gh-docs with DocFX, but it did not grab anything out of the code.

I would appreciate help with this if anyone has done it successfully.

[dandago]

I don't know whether DocFX picks up XML documentation from the code - as far as I can tell, in Orleans it's only used to transform the markdown docs into HTML output.

For the XML docs you'll need a tool such as Sandcastle (or whatever similar tool is used nowadays).

[jason-bragg]

Let's start with a narrow target for this, maybe Orleans.Core.Abstractions?

[JillHeaden]

I got this to work as far as generating the documents.

The walkthrough provided here produces the result: https://dotnet.github.io/docfx/tutorial/walkthrough/walkthrough_create_a_docfx_project_2.html

This issue can be closed.