Joe in Iowa – A Sandcastle Scenario

re: Joe in Iowa – A Sandcastle Scenario

RubenP — Wed, 09 Aug 2006 00:22:49 GMT

Just wondering, but does Sandcastle support real HTML docs (or HTML + JavaScript docs) like MSDN online? NDoc did (really well), and so does JavaDoc (a little less well), and I must say, that's a real 'selling point' for me. And I mean by default, not a pointer to some blog that tells you roughly how to reinvent the wheel by yourself, but leaves the complete working solution as an excercise to the reader. ;-)

I really *hate* it if I need to download a CHM or MSI file and deal with all the security worries that such a method entails. (CHM's are a security breach waiting to happen and you usually need admin rights to run an MSI). And Document Explorer is just so insanely slow to use. I want to *read* documentation, not wait a minute before the viewer it finally starts and even then wait 5 seconds between each page transition.

But with a website, you just point yourself (or a customer) to a url and hey presto. Compiling plain HTML pages is a lot faster when you're fixing up your documentation. Refresh - check - fix - compile - refresh ... The HTML Help compiler requires you to close your files when you're compiling, and takes ages to complete. (Hmmm, I'm starting to see a pattern here...)

re: Joe in Iowa – A Sandcastle Scenario

aram — Wed, 09 Aug 2006 03:36:50 GMT

Sandcastle generated HTM files. If you look at this blog it's eamplained above the "Packaging" section.

re: Joe in Iowa – A Sandcastle Scenario

aram — Wed, 09 Aug 2006 03:37:26 GMT

Sandcastle generated HTM files. If you look at this blog it's explained above the "Packaging" section.

re: Joe in Iowa – A Sandcastle Scenario

andlju — Thu, 10 Aug 2006 13:44:00 GMT

I've now done the third post explaining some of the inner workings of Sandcastle. So the series is now complete:

http://blog.ljusberg.com/2006/08/sandcastle-under-hood-part-1.html
http://blog.ljusberg.com/2006/08/sandcastle-under-hood-part-2.html
http://blog.ljusberg.com/2006/08/sandcastle-under-hood-part-3.html

/Anders

re: Joe in Iowa – A Sandcastle Scenario

RubenP — Tue, 15 Aug 2006 01:08:50 GMT

Well, you've got HTML and you've got HTML. I don't expect to be using the same HTML for a CHM or a website; are you? Could you perhaps post an example of an in-box pure HTML run *as a web site* as opposed to a bunch of files?

Still a bit in the wait-and-see mode, with the early-but-not-wholly-unexpected demise of NDoc.

re: Joe in Iowa – A Sandcastle Scenario

aram — Tue, 15 Aug 2006 01:47:10 GMT

Ruben,
We do not have an example which will generate an out of box 'website" from Sandcastle. If you provide us a scenario I will be happy to consider this as feature.

Anand..

re: Joe in Iowa – A Sandcastle Scenario

RubenP — Wed, 16 Aug 2006 00:09:28 GMT

Well, it seems this scenario is a little hard to grock unless you've seen it in action. Ever tried NDoc or JavaDoc? If you haven't (being Microsoft employees and all), you really should.

Wat you do with NDoc, is that you specify the XML comment file(s), and tell NDoc what parts of the object model you do and do not wish to generate documentation for (internals private methods, warnings for missing documentation, etc.) Then you select a template (such as MSDN-like), and after pressing the Build-button, NDoc generates all HTML files, with cross references, index pages, supporting JavaScript, css and images, and puts them in a directory (specified by the user). When NDoc is done, you just open index.html and you've got the complete documentation of your library at your fingertips, with a navigation pane, etc., except for a search-page.

If you look at http://ndoc.sourceforge.net/reference/, you'll find an example which was generated directly from the predefined MSDN template.

You should also take a look at http://ndoc.sourceforge.net/usersguide.html, especially the Tag reference, as the users of NDoc discovered that the standard comment tags are, erm, lacking. These extra tags were impemented mostly through extra XSLTs, but they were both documented and supported, so you didn't have to re-invent the wheel every time.

A full document builder is fine, but you do need to keep an eye out for the projects that don't involve a team of 10+ documentation writers.

re: Joe in Iowa – A Sandcastle Scenario

aram — Wed, 16 Aug 2006 00:42:05 GMT

Ruben,
Thanks for your comments. I have not triend nDoc or Java Doc. However I will and it looks like we can address all the scenarios you have mentioned. We do plan to provide MSDN styled templates.
As I mentioned at http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=617698&SiteID=1 we do plan to support all additional tags including user defined tags.

Anand..

re: Joe in Iowa – A Sandcastle Scenario

RubenP — Fri, 18 Aug 2006 15:04:24 GMT

Great. Looking forward to the upcomming CTPs.

re: Joe in Iowa – A Sandcastle Scenario

Charlie Rieder — Thu, 24 Aug 2006 12:37:40 GMT

Anand,
have a look at http://www.codeproject.com/useritems/SandcastleBuilder.asp
IMHO Eric has created an excellent tool for Sandcastle, aimed at NDoc users.

Sandcastleのメモ

Miscellaneous — Thu, 04 Jan 2007 05:41:20 GMT

Sandcastle - December 2006 Community Technology Preview (CTP)を使ったメモ

※現状では、結局chmの作成はできなかったけど、とりあえずHTMLが作成できたからOKとしている状況。HTMLが2万近くあるからなんとかchmにしたいけれど。。。作業ディレクトリは C:\Program Files\Sandcastle\TEST\Doc。ソリューションが全部入っているディレクトリ以下に存在するdebugフォルダを全部作業ディレクトリにコピーする