Benchmarkdotnet: Online documentation and API reference

[AndreyAkinshin]

Now we have almost all our documentation in a single README file. The documentation is great, but the file is too big, it's hard to maintain it, it doesn't include the API reference. Possibly, it makes sense to use a tool for automatic documentation generating. For examples, DocFX looks good. We can integrate it to our CI build and generate docs fully automatically.

@mattwarren, @adamsitnik, what do you think?

Current status

• [X] Guide
• [X] API Reference

[adamsitnik]

it makes sense to use a tool for automatic documentation generating

Would you like to generate it from the comments from source code?

Maybe we could create a github.io web page with tutorial that tell how BDN works and how to use it?

[AndreyAkinshin]

Would you like to generate it from the comments from source code?

API reference from xml-docs in the source code, Guide from a set of markdown files.

Maybe we could create a github.io web page with tutorial that tell how BDN works and how to use it?

Yes!

[FransBouma]

Besides DocFX, you can also use DocNet (disclaimer: I wrote it). The advantage of DocNet is that it can autogenerate your ToC from headers and can deal with deeper nesting than DocFX. Of course it's suitable for automatic generation of a documentation website (we generate all our docs using it automatically).

It's not suitable for pure API docs, it only consumes md files which form a documentation site. I'd go for sandcastle helpfile builder for that (https://github.com/EWSoftware/SHFB) as it can output to multiple formats (e.g. offline documentation sets in vs.net format, for the people who want those).

If you want, I can chop up the readme.md into a website with DocNet. :)

[FransBouma]

Is this still up for grabs? Should I go ahead and create a documentation site from the readme using DocNet?

[adamsitnik]

Is this still up for grabs? Should I go ahead and create a documentation site from the readme using DocNet?

@FransBouma Yes. That would be great!

[AndreyAkinshin]

@FransBouma, sounds great! I have only two requests:

1. We still need the API reference. Can you implement it?
2. It would be cool two have at least two version of the documentation: for the latest stable version and for the latest commit from the master branch (for example, see http://nodatime.org/). Is it possible to do it with DocNet?

[FransBouma]

I've created a gh-pages site. As there's no gh-pages branch in the root repository, I can't create a PR, but it's located here: https://github.com/FransBouma/BenchmarkDotNet/tree/gh-pages

Viewed here: https://fransbouma.github.io/BenchmarkDotNet/

I used the default theme, colors can be changed if you want, it's just a css file in a theme folder. The docs are generated using DocNet v0.13: https://github.com/FransBouma/DocNet/releases/tag/0.13, I included a .cmd file to generate the site, which simply contains docnet . and it will generate the htm files in the folder above it. I kept the MarkdownSource folder in the gh-pages branch, but you can of course locate it elsewhere. If you want to add a page, simply add it to docnet.json, no need to add the ToC topics, those are autogenerated.

The site's source files are in MarkdownSource folder in that branch.

@AndreyAkinshin

1. You mean setup the auto generation of an API site? I'll look into it. Will be next week I think before I have something. I'll use sandcastle helpfile builder, as I use that myself too for our api docs.
2. Sure, it's just a set of .md files with a config which is used to generate .htm files. So you can simply branch the folder with the .md files, alter them for the next version and generate a different site in a different folder. From the looks of it, Jon does that with nodatime too :)

Hope this helps! I corrected some texts too along the way, not too much.

[AndreyAkinshin]

@FransBouma, looks awesome, thanks! Waiting for the PR.

I'll use sandcastle helpfile builder, as I use that myself too for our api docs.

Ok.

[FransBouma]

@AndreyAkinshin I can't create the PR yet, you first have to create an empty gh-pages branch :), as gh-pages branches only contain the site content, not the code.

So please add a gh-pages branch to this repo, then select it as the current branch and then remove all files. Then commit. You'll then have an empty gh-pages branch in this repo here. I can then create a PR against that. I can now only create a PR against 'stable' or one of the other branches, but that doesn't work as github will then merge the gh-pages branch in the main branch removing all files ;)

[AndreyAkinshin]

I will update gh-pages myself. Now I want to have changes in the master branch that allow to build the documentation from the current sources.

[FransBouma]

I will update gh-pages myself. Now I want to have changes in the master branch that allow to build the
documentation from the current sources.

Ok, so I should add the .md files in a folder to the master branch? Will do that. Will also alter the docnet.json file a bit so it will generate to a folder and clear it on every generation. You can then copy these files to the folder you have intended for gh-pages or a folder inside that. :) 

    Frans

[FransBouma]

I've added the PR. I'll add the reference manual docs generation script / config files to documentation\referencemanualsource so you can then use that to create the output and place it where you want it. Will be next week though. Cheers :)

[FransBouma]

As for the reference manual: most public methods and classes have no xml doc comments whatsoever. Generating any documentation from that isn't really helpful, it will more or less be empty. So to get a reference manual that is actually useful, there first have to be xml doc comments in the code. So till then, generating a reference manual is not really going to help.

[AndreyAkinshin]

Xml doc comments are in the nearest plans. However, I want to have an ability to generate reference manual first.

[FransBouma]

Heh, yeah they always are.

[AndreyAkinshin]

Hooray, now we have online documentation: https://perfdotnet.github.io/BenchmarkDotNet/

Now it's about the latest version of the master branch. After v0.9.9, it will describe the latest stable version of the library. In this case, we will not need stable branch at all because we will have online documentation instead of the README file.

/cc @adamsitnik, @mattwarren

[FransBouma]

You changed something in the stylesheet, perhaps? The perma link icons are really huge now and lineheight is bigger than by default in the menu. (I see a.headerlink is missing in theme.css )

[adamsitnik]

@FransBouma thank you! great job. It's kind of weird to me now that finally we have nice docs ;)

[AndreyAkinshin]

@FransBouma, no, I just downloaded Docnet v0.13 and ran GenerateHtml.cmd.

[FransBouma]

Then I have a bug to fix in the releases, I think as the theme.css in default is then not up to date :( I'll get back to you.

[FransBouma]

@AndreyAkinshin Could you try with the new release 0.13.1? Contains 0.13 binaries but updated theme files. the ones shipped with 0.13.0 were seriously outdated :X

[AndreyAkinshin]

@FransBouma, done: https://perfdotnet.github.io/BenchmarkDotNet/

[FransBouma]

Much better! :) :+1:

[FransBouma]

Api docs generation is now available through the PR. It requires sandcastle helpfile builder. this is an OSS tool but I don't know whether appveyor has it (but as it's the only free, and solid, api doc generator out there I think they do). Docs look like MSDN (and have the same layout like the ones from json.net as that's also generated with SHFB)

[FransBouma]

I saw your addition in the form of 'Overview', which is OK, and I hope you don't take this the wrong way but please avoid trying to re-do the docs in compressed format in an overview page. Before you know it, you've duplicated docs which isn't really helpful and you still have a large page like you do now ;) It's easy to fall into this trap, I've done that many times.

An idea could be to link to documentation segments which actually describe the material you mention, so the user can quickly find it. Also, it might be a good idea, if things grow, to have two sections in your docs: a 'how to' section and a 'functional reference' section. The how-to section describes typical actions and refers to the functional reference sections for details. The functional reference sections are dry descriptions of how things work. IMHO this works better than an 'overview' page as often applications, also BenchmarkDotNet, tend to have a lot of features and it's hard to compress it all in one page, as it's often impossible to choose which feature _not_ to mention there. ;) Just a tip ;) Cheers.

[AndreyAkinshin]

@FransBouma, thanks for the advise!

My idea is the following: I want to describe very briefly our main features (right now in README there are a lot of details). Each section of overview will have links to the corresponded sections of the documentation.
I want to put detailed docs into separated pages, it will be really helpful for people who already use BenchmarkDotNet and want to know more about it. But I want to have a place for new users where they can learn how powerful the library is.

[AndreyAkinshin]

@FransBouma, ok, I finished the overview: https://perfdotnet.github.io/BenchmarkDotNet/Overview.htm Now it contains only main features with super briefly explanation/examples and links to the corresponded sections (where you can read about these features in detail). I think, this page will be very useful for people who want to know what BenchmarkDotNet is.

[FransBouma]

@AndreyAkinshin Looks great! Just enough info to get one interested and not too long overall. :) :+1:

[AndreyAkinshin]

Thanks!