16

I'm just wondering - the last release of Sandcastle is from May 2008, and it's still listed as Pre-Release Software/CTP and it's not even licensed anymore, as the EULA specifially says:

2.TERM. The term of this agreement is until September 1, 2007, or commercial release of the software, whichever is first.

As Sandcastle is rather "heavy" anyway, I just wonder if it is still the right thing to use, or if there are alternatives to create XmlDoc Documentation? (Alternatives = something I can run from my build to generate at least HTML, preferably PDF as well).

Michael Stum
  • 167,397
  • 108
  • 388
  • 523

7 Answers7

13

Microsoft Sandcastle is definitely still the right way to go. The main alternative (that offers anything close to the feature set of Sandcastle) is NDoc, but the last release of that is much older, being in January 2005!

Although it is still technically in (late) pre-release stage, it is in fact quite a stable tool. The small number of bugs have been fixed by patches, available on CodePlex as part of the Sandcastle Styles project. There's also a superb GUI for it, namely Sandcastle Help File Builder.

I am not sure about the future development of Sandcastle however. I believe it is likely Microsoft will continue work/expansion on it at some point, though there doesn't seem to be any news of when. It is certainly the only decent tool for creating proper documentation for a .NET library or application, at the moment. Of course you can often get away using more "light-weight" tools for small projects/help files. The main alternatives that I've noticed are both commercial and inferior to Sandcastle.

Generating documentation by hand/using custom automation is probably feasible in certain cases, but only for small projects (that are not likely to expand.)

GWLlosa
  • 22,656
  • 17
  • 75
  • 108
Noldorin
  • 134,265
  • 53
  • 250
  • 293
  • +1 for mentionning Sandcastle Help File Builder, which I used to generate the docs in 3 clicks. – CharlesB May 24 '10 at 17:09
  • 1
    FYI, according to the Sandcastle CodePlex site, "The Sandcastle CodePlex project is no longer under active development by Microsoft" (http://sandcastle.codeplex.com/). This doesn't mean you shouldn't use it. It just means that you will need to look to the SHFB creator for future support (http://shfb.codeplex.com/). – blachniet Oct 26 '12 at 12:02
13

Nobody mentioned Docu, a recent project initiated by James Gregory, dev lead on FluentNHibernate.

It's a very simple and easy to use tool that generates html documentation a la rdoc. You can easily modify templates since Docu uses Spark as the view engine.

Here is the FluentNHibernate documentation built with Docu.

Romain Verdier
  • 12,297
  • 7
  • 53
  • 77
  • 2
    The FluentNHibernate Documentation looks awful, but Docu looks interesting, because he summarized some of my concerns (having to chain several applications using a weird syntax). Going to have a closer look. – Michael Stum Jun 12 '09 at 14:25
  • Nice, Docu already works very well. I am not 100% sure if I'm going to miss separate Pages for every function, but the low-friction template generation and the ease of use (no weird deployment) already impress me. – Michael Stum Jun 12 '09 at 14:48
  • For other's information, Docu is still alpha, and crashed on working generating my project – CharlesB May 24 '10 at 17:10
  • Docu seems to have stagnated, it also doesn't build .exe assemblies – Chris S Aug 28 '10 at 19:12
  • @Chris: You can try to ask James Gregory (http://twitter.com/jagregory) about Docu status on twitter. – Romain Verdier Aug 30 '10 at 07:23
  • Docu is still alive, just dormant; it does most of what I need from it right now, so activity has been minimal. There's a [mailing list](http://groups.google.com/group/docu-group) where you let us know about issues, and make suggestions for improvements. I've got a lot of plans for Docu, it's just finding the time to action them that's an issue! – James Gregory Nov 09 '10 at 09:33
3

To effectively use Sandcastle you need, as Noldorin pointed out earlier, to also use Sandcastle Styles and Sandcastle Help File Builder (SHFB). They all had a new release in mid-2010 so are definitely current tools.

Even with the clean and simple GUI provided by SHFB, however, there are quite a number of issues that you may need or want to consider in order to produce a tidy, professional documentation set. My article ("Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code") documenting my experience with a variety of potential pitfalls, published on Simple-Talk.com in September 2010, may save you some time, effort, and agony :-).

Another helpful resource: In October 2010 I followed up the article with a one-page wall chart that summarizes the XML documentation comment lexicon for SHFB.

Michael Sorens
  • 32,325
  • 20
  • 111
  • 165
3

As far as I'm aware, Sandcastle is still a valid choice. I've used it many times in the recent past and have no issues. You can check out this page on MSDN and scroll down to the 'Documentation' section for other good choices:

C# Programming Tools

Justin Niessner
  • 229,755
  • 35
  • 391
  • 521
1

I put a short list of some documentation tools in this SO question: anyone-using-ndoc-or-a-similar-tool

I think SandCastle is the best opensource tool currently (for documenting .NET projects), but there are several commercial tools, and they can propose better performance and more features, so if you have a budget for one of them, it worth at least evaluating what value it could bring to you.

Community
  • 1
  • 1
Bogdan_Ch
  • 3,146
  • 4
  • 20
  • 37
1

Sandcastle is still a right choice. I used it for many projects in past.

Anyway take at look at these:

NinethSense
  • 8,036
  • 2
  • 21
  • 23
1

DocProject is worth taking a look at. It takes away a lot of the pain of working with sandcastle.

pjbelf
  • 641
  • 4
  • 4