Yes, excellent pt. I imagine with links to SandCastle, help compilers, etc as needed.
We might actually also consider KEEPING installs of all this stuff downloadable from us (NH) so that we can ensure correct versions of these things, etc (e.g. proper CTP build of sandcastlean etc) so long as this doesnt violate some distro lic agreement for these tools. -Steve B. -----Original Message----- From: Fabio Maulo <[email protected]> Date: Mon, 30 Mar 2009 10:56:50 To: <[email protected]> Subject: [nhibernate-development] Re: Build-integrated API Reference HELP system Evaluation Only to no forget it...The other thing needed is a HowTo_CompileDocumentation.txt with all info/links needed before run the NAnt/MsBuild task. 2009/3/30 Stephen Bohlen <[email protected]> > Great idea. > > Something like... > > nant reference-api-docs > > ...or similar. > > Since I wasnt working w the NH source but rather the binaries, I was > testing purely in VS and not considering that (of course) the build scripts > = the way NH gets compiled rather then using 'pure' VS 'F6' to > compile/build. > > -Steve B. > > ------------------------------ > *From*: Fabio Maulo > *Date*: Mon, 30 Mar 2009 10:43:50 -0300 > *To*: <[email protected]> > *Subject*: [nhibernate-development] Re: Build-integrated API Reference > HELP system Evaluation > > +1 DocProject > About compilation we may use an explicit NAnt/MsBuild task. > > P.S. don't sorry for the length of the mail. > > 2009/3/29 Stephen Bohlen <[email protected]> > >> All: >> >> As I committed to in a prior thread ( >> http://groups.google.com/group/nhibernate-development/browse_thread/thread/729819b625001217 >> ) >> I have now completed a preliminary review of the two possible approaches to >> auto-generating API docs for NHibernate from the XML code comments as part >> of our build process. >> >> Recall that one suggestion (offered by Will) was to investigate James >> Gregory's new alpha build of 'Docu' ( http://docu.jagregory.com/ ), the >> light-weight code-comment-compiler he wrote for generating help content for >> the Fluent NHibernate project and offered as OSS to anyone wanting to use it >> for any other project. I countered that we should also consider the more >> robust DocProject ( http://www.codeplex.com/DocProject ) app that shields >> the developer from having to interact with the incredible complexity that is >> the SandCastle + MSHelp compiler infrastructure from MS. What follows are >> the results of my doing just that. >> >> Test platform: >> Dell D830 laptop, Intel Core 2 Duo, 32-bit WinXP/SP3, 4GB RAM >> Visual Studio Pro 2008 SP1 >> NHibernate 1.2.1 GA release (binaries and XML comment files, no source >> needed) >> >> Test platform notes: I used the 1.2.1 GA release of NH just because its >> what I happened to grab off my hard drive at first; I have no reason to >> believe that the results of any of my tests would be materially affected by >> running them on any subsequent build/release/version of NH so I don't think >> this to be an impact on the tests or their results. >> >> ***Docu Testing and Observations*** >> >> Docu works by simply firing off a command-line and passing it the path to >> your binary (nhibernate.dll in this case). It then constructs pure HTML >> output that can be loaded/viewed in a browser without needing to be hosted >> on a webserver (though the content could of course be posted to a web server >> for others to view as desired). >> >> From the get-go, I had a number of issues (unhandled null-reference >> exceptions) thrown by the Docu EXE iteself when operating on the >> NHibernate.dll and its XML code comments. I eventually grabbed the latest >> code from Docu's hosted location on GitHub and built it myself in VS. The >> latest code had the same unhandled exceptions but at least with the code in >> hand I could troubleshoot the issue(s) myself :D >> >> My 'fixes' to Docu probably aren't worth committing back to that >> project since most of them basically checked for null instances of variables >> at critical points and return from the methods if nulls are passed to them >> (probably NOT the desired behavior, but certainly enough for me to get Docu >> to successfully produce output from the nhibernate.dll assembly without >> throwing exceptions). I have no idea if these exceptions are due to >> any strange (unexpected?) syntax we are using in the code comments within >> the NHibernate codebase or are simply the result of Docu being in >> early-alpha and not properly handling otherwise legitimate code comment >> syntaxes, but none-the-less we need to be aware that as it exists RIGHT NOW >> TODAY, Docu and the NHibernate project's XML code comments are fundamentally >> incompatible with each other without there being changes to at least one or >> the other :( >> >> Once I tweaked the Docu souce code to successfully run against >> the NHibernate.dll without throwing null-reference-exceptions, I was able to >> produce the API refererence docs that I have posted on my server for >> download by anyone interested at the following URL: >> http://unhandled-exceptions.com/downloads/NHibernate_121_Docu_Test.zip. >> The good news is that this documentation is light-weight (pure HTML) and the >> ZIP file is barely 2MB in size for the entire help collection. To view the >> results, unzip it somewhere and just click on the index.htm to load the >> 'site' in your browser of choice. >> >> The generation of these comments by Docu is *NOT* speedy; Docu took >> approximately 15+ minutes to generate the output, most of that was spent >> with my dual-core processor locked @ 50% utilization with near-zero disk >> activity, suggesting that Docu is processor-bound in its performance and >> expects and uses just a single core to do its work (suggesting that throwing >> more hardware at it isn't likley to help much unless/until Docu becomes >> multi-threaded). Significant disk activity only occured briefly at the end >> of the 15 minutes when the final output was rendered to the files included >> in the aforementioned ZIP file, suggesting that the compilation isn't disk >> I/O-bound at all. >> >> This suggests that even though running Docu is as simple as passing a >> single-argument command-line to it, its largely infeasible to invoke it as >> part of *every* build sequence while someone was working on the NH codebase >> since the post-build documentation compilation step would take a >> prohibitively long time. It might be reasonable to setup Docu to run >> remotely on some dedicated CI build-server (e.g., the codebetter teamcity >> installation, etc.) so that it happened post-checkin, but due to the long >> runtime for the doc-compilation process, its nearly certain that this >> process would always have to run out-of-band as a developer worked on the >> project and made their check-ins. >> >> Since all that's needed is a single command-line invocation, integrating >> Docu into the CI server's build process would be trivial and Docu's lack of >> dependency on any other infrastructure (e.g., SandCastle, help compilers, >> etc.) makes it trivial for anyone to run the thing themselves were they to >> check out the source to their own PC (although as mentioned, they would have >> to wait the 15+ minutes for the process to run to completion were they to >> invoke Docu against the project). >> >> >> >> ***DocProject Testing and Observations*** >> >> DocProject is a significantly more complex and signficantly more >> feature-rich XML code-compilation solution than Docu. This is both a >> positive (better, more useful API reference compilation) and a negative >> (significant complexity and dependencies on other tools, etc.). >> >> DocProject works by automating the MS SandCastle infrastructure and, >> optionally, the MS Help compiler v 1.x and/or v 2.x to produce its output. >> As such, these dependencies have to be present (and properly installed) in >> order for DocProject to funciton properly. The good news is that once this >> is accomplished, DocProject is capable of producing compiled help as a >> single .CHM file, a .HxS visual-studio-integrated help file that can be >> installed right into the VS help subsystem and accessible via F1 from within >> Visual Studio, and a complete ASP.NET web site that can be deployed to a >> server for wider access to the content. As DocProject installs and is >> controlled as a new 'project type' in Visual Studio, you select as part of >> the New-Project-Wizard in Visual Studio which of these output targets you >> are interested in compiling to. >> >> I had little trouble getting DocProject up and running on my system; after >> installation of the SandCastle infrastructure and the requisite MS help >> compilers, the DocProject installer capably interrogates the registry to >> discover the paths to these items and wires itself up to them just fine. >> Once installed, I need not interact with the underlying components at all >> and can control/confgure the behavior of the compiled help output solely >> from with Visual Studio by editing the DocProject settings for the custom VS >> project type. This makes for a familiar UI (build property pages, etc.) for >> configuring the output of the system. >> >> Performance of the DocProject system in generating the help output was no >> better (or worse!) than that of Docu, taking about the same 15+ minutes to >> produce its output. This suggests that performance/speed isn't a factor in >> determining which of these directions to pursue. There doesn't seem to be a >> significant change in the compilation time based on what output targets you >> select (e.g., CHM, ASP.NET web site, etc.) so I am strongly guessing that >> the vast bulk of the 15+ minutes is spent in processing the comments rather >> than spitting them out to actual help artifacts. Since this is about the >> same 15+ minutes that Docu took, I'm going to conclude that there is little >> that could be done to reduce this processing time significantly. >> >> The results of my running the nhibernate.dll and its related comments >> through the DocProject process are posted for download by anyone interested >> at the following URL: >> http://unhandled-exceptions.com/downloads/NHibernate_121_DocProject_Test.zip. >> Becuase the DocProject output is a complete >> ASP.NET web site including graphics, icons, etc. instead of just standard >> HTML and because this download also contains the complete CHM file, this >> download is over 90+ MB in size. Since its an ASP.NET web site, to view >> this content you will need to unzip it somewhere and then point an IIS >> virtual directory to it in order to view/consume it. Once you do this, the >> website also contains a link (in the upper right) which leads to the >> compiled 15 MB .chm file if you are interested in seeing that content as >> well (but it looks almost 100% identical to the ASP.NET content, so not >> much need for that). >> >> DocProject is (ultimately) invoked from MSBUILD, and so it would be >> possible to wire it up as well as a post-build event or a CI task that >> automatically happened out-of-band when code is checked into the repository >> (just as with Docu) but since its MSBUILD this task-integration would >> probably be more complex than the simpler command-line invocation that Docu >> provides. Also, since DocProject is dependent on Sandcastle and the MS help >> compilers to do its work, these dependencies would need to be >> installed/configured on whatever CI platform invoked the API Reference >> compilation step of course. >> >> >> >> >> ***SUMMARY OF COMPARISON*** >> >> Docu >> --------- >> Pros: >> >> - simple to configure/invoke >> - no external dependencies on other tools >> - light-wt output (small output size 2MB+/-) >> - final output can be viewed in browser w/out a web server (e.g., just >> HTML files) >> - web output can be posted to a non-IIS/ASP.NET web server for public >> access >> >> Cons: >> >> - early alpha tool >> - presently throws exceptions and crashes when pointed at the NH >> project :( >> - no search capability in the output (beyond CTRL+F on page-by-page >> basis); intended usage pattern seems to be BROWSE, not SEARCH >> - no single-file output target (e.g., CHM) >> - no integration of output with Visual Studio Help system >> - takes 15+ minutes to run >> >> >> DocProject >> ---------------- >> Pros: >> >> - output looks/feels like rest of Microsoft (MSDN) help and offers >> familiar navigation of content >> - offers single-file output target (CHM) >> - output is searchable in its entirety at once (vs. page-at-a-time) >> - index automatically built and integrated into output >> - Visual Studio integrated help can be an output target >> - configuration is performed in a familiar environment (Visual Studio) >> >> Cons: >> >> - external dependency on MS tools (sandcastle, help compilers, etc.) >> - significantly larger website output (90+ MB) >> - web content needs IIS/ASP.NET to host it for public access >> - more complex process of integrating it into build scripts >> - takes 15+ mnutes to run >> >> >> ***RECOMMENDATION*** >> >> IMO the DocProject approach is the more robust of the two options, >> offering a more familiar presentation of content to the end-user and richer >> experience in interacting with the content (e.g., integrated seach, indexed >> keywords, etc.). If we are going to bother to do this, I think it would be >> most valuable to do it in a way that the resulting content is the most >> approachable and the most usable by as many people as possible and IMO >> that's the output provided by the DocProject approach. It offers the >> web-based content that should be posted to the internet as well as the CHM >> file for those wanting offline reference to the content. For the >> adventuresome, there is even the VS-integrated content making the NHibernate >> API reference a full-fledged participant in the VS help system (supporting >> valuable learning scenarios such as placing your cursor on an NH >> class/method and being able to jump to help on it via a simple F1 keystroke >> from inside Visual Studio -- followed, sadly, by the interminable 10-minute >> wait for the VS help system to spool up and load, of course!). >> >> The biggest challenge to the DocProject approach IMO is the dependency on >> SandCastle, the MS help compilers, etc. and if the DocProject help generator >> VS project were added directly to the NHibernate trunk solution, then anyone >> interested in building NH would need to either unload the DocProject VS >> project from the solution or else get all of those dependencies installed >> just to build/compile NH and that's too high a burden to ask anyone to >> achieve if all they want is to check out the core NH project and >> build/compile it for themselves IMO. >> >> One of the important things to understand about *either* of these help >> compilation tools is that neither of them actually require access to *any* >> of the NH source code directly -- instead they simply require access to the >> compiled binaries and the XML code-comment files extracted from the source >> code by the C# compiler at build-time. This actually means that I think the >> best way to accomplish the creation of a rich API reference for NH is to >> create a separate parallel solution (NH_API_Reference?) that is *not* part >> of the main NH solution but contains (relative) path-pointers to the >> location of the compiled NH binaries from the actual NH solution itself. >> This way, the 'API Reference Project' can be completely separate and >> distinct from the actual NH source trunk. >> >> This would support the following scenarios: >> >> 1) if you want to build just NH, you get that trunk and build it; the sln, >> nant scripts, etc. make no refernece to the DocProject stuff at all and >> nobody is affected (nobody needs SandCastle, MS Help compilers, etc. to >> build the NH trunk just as is the case today) >> >> 2) if you want to build the API ref docs, you check out BOTH the NH trunk >> and the API_REF trunk, build the NH trunk, and then build the API_REF trunk >> that points to the bin output folder from the NH source trunk to get the >> binaries and the XML it needs to process; this scenario would (of course) >> require you to have installed SandCastle, the MS Help compilers, etc. in >> order to perform the compilation of the API reference docs but only such >> people would be affected >> >> It seems to me that this would support the needs of everyone in a way that >> would have the least negative impact on the 'real' NH source trunk and yet >> still permit us to construct the most robust API reference content for any >> NH adopter. >> >> Sorry to all for the (ridiculous) length of this thing, but as this is >> hardly the kind of decision I think I should (could!) make on my own, I >> wanted to try to summarize as much of my findings as I could so that >> everyone can understand the factors that will play into our decision and >> help form the basis for any discussion anyone wants to have about how best >> to proceed. >> >> Thoughts (as always) welcome; I'm sure I'm overlooking several pros and >> cons for either solution so am hoping a discussion here about this will >> surface some of my oversights. >> >> -- >> Steve Bohlen >> [email protected] >> http://blog.unhandled-exceptions.com >> http://twitter.com/sbohlen >> > > > > -- > Fabio Maulo > -- Fabio Maulo
