My opinion is that: SVN should not hold generated files, including XML/HTML docs.
The *binary* release packages should contain the .xml files so that VS can intellisense intelligently against the DLLs, and that HTML docs should be included so they are available online or offline. But... online HTML should be the gold standard, and be up to date w/ SVN at all times via post-commit hooks that trigger Sandcastle rebuilds. -T On Tue, Sep 20, 2011 at 10:40 PM, Michael Herndon <mhern...@wickedsoftware.net> wrote: > I'm with you on checking in the static files into ~/site/doc/version > > that would be pretty easy to automate from jenkins & msbuild if we can get > the docs into static html. > > I currently just push all assemblies, help files, xml docs into ~/trunk/bin > on the user's local once the scripts finish building, running tests, and > reports. Nothing gets commited into svn from this at the moment. The site > is generated, but not pushed anywhere. > > I was waiting to see how aspx thing plays out & getting CI up with nuget > before setting up a build release build task that automates everything > including pushing the docs, finalized content, etc. > > So my real question is, do we need to store static docs that are generate in > ~/trunk/docs/? > > If so, could we store those in a single file format and just provide a setup > script that takes care of extracting the latest for the user versus putting > all those files into trunk. > > Technically someone could build an post process hook that builds up a static > html index from xml & bin files, but I'm hoping it does not come to that. > > > - Michael > > > > > > > > On Wed, Sep 21, 2011 at 12:56 AM, Troy Howard <thowar...@gmail.com> wrote: > >> Why would we want to do that? >> >> Under the /site/docs directory, they need to be served up as loose HTML... >> >> IMO the XML files shouldn't be checked into SVN because they are >> auto-generated. The same goes for Sandcastle files.. However, in the >> release packages, I think we should include the XML files as well as a >> fully functional version of the Sandcastle docs that can be viewed >> locally. I personally thing CHMs are terrible user experience, and I'd >> much rather have a static HTML site I can browse locally, if we're >> going to bother including a copy of the documentation in the package, >> vs just hosting it online and calling that good (this is what most >> projects these days do). Good thing about hosting online -- searchable >> via google. >> >> Thanks, >> Troy >> >> >> On Tue, Sep 20, 2011 at 9:48 PM, Michael Herndon >> <mhern...@wickedsoftware.net> wrote: >> > Could we store sandcastle docs as a single zip/chm? >> > >> > >> > >> > On Wed, Sep 21, 2011 at 12:37 AM, Troy Howard <thowar...@gmail.com> >> wrote: >> > >> >> At one time I had a SVN server set up at work that had a post-commit >> >> hook set up that would generate a static HTML site from the XML doc >> >> files using Sandcastle. So.. It can be done. That was about 3-4 years >> >> ago and I don't work at that company any longer, so I don't have >> >> access to the details of how that was done. >> >> >> >> Regarding SVN locations... >> >> >> >> Autogenerated XML doc files should go in the ~/trunk/doc/<component> >> >> folders. The Sandcastle generated static HTML should go under >> >> ~/site/docs/<version> folders. >> >> >> >> I'll see if I can't dig up some info on how to generate static HTML >> >> with Sandcastle. >> >> >> >> Thanks, >> >> Troy >> >> >> >> >> >> On Tue, Sep 20, 2011 at 9:15 PM, Michael Herndon >> >> <mhern...@wickedsoftware.net> wrote: >> >> >>We have a folder /trunk/docs, shouldn't this be the place for that? >> >> > >> >> > We should have a live site for the documentation that people can >> browse, >> >> > similar to the parent project's site. >> >> > http://lucene.apache.org/java/3_4_0/api/all/index.html. It makes it >> the >> >> > documentation more accessible. >> >> > >> >> > The rub is that Sandcastle & SHFB generates html files with guid >> names, >> >> xml >> >> > & bin files that map to the html files, and aspx pages which acts as >> the >> >> > glue. The aspx pages parses the xml/bin files which creates the >> document >> >> > site. Thus we're now required to use a server that knows how to serve >> up >> >> > aspx pages. >> >> > >> >> > If any one knows a way to generate just vanilla html using Sandcastle >> & >> >> > SHFB, I could just create a folder per version and push the docs to >> >> > incubator site. But so far I haven't found an option for this. >> >> > >> >> > Keeping the generated help docs inside of source would still require >> for >> >> > users to setup a local website just to view the documentation and it >> adds >> >> > extra noise in the project. >> >> > >> >> > In the release we can provide a zipped file of the site and a >> generated >> >> .chm >> >> > or even help2/3 files. >> >> > >> >> > On Tue, Sep 20, 2011 at 11:38 PM, Prescott Nasser < >> geobmx...@hotmail.com >> >> >wrote: >> >> > >> >> >> >> >> >> > >> >> >> > We should probably fix the ClsCompliance warnings if they have not >> >> >> already >> >> >> > been fixed >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> We will have some issues with this - some are marked volatile - which >> >> >> basically have to be a non-CLS compliant type (as far as my research >> is >> >> >> finding) Anyone have thoughts? I went through and replaced sbyte -> >> >> Int16, >> >> >> and uint -> Int64, but I'm having an issue with this, and I don't >> think >> >> >> removing the volatile keyword is the right solution. >> >> >> >> >> >> >> >> >> >> >> >> > find a place to put the generated documentation. >> >> >> >> >> >> >> >> >> We have a folder /trunk/docs, shouldn't this be the place for that? >> >> >> >> >> >> >> >> >> >> >> >> > >> >> >> > I remember someone mentioning he/she was unable to access a class >> from >> >> >> > VB.NET. The class had public fields & properties with the same >> names >> >> but >> >> >> > different casing. The fields should be private. >> >> >> > >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> > The link in the readme is a dead link: >> >> >> > http://lucene.apache.org/lucene.net/docs/2.4.0/ The docs generated >> by >> >> >> > sandcastle & SHFB require a server that allows aspx files to be >> >> executed. >> >> >> > We should either remove the link from the readme or find the docs a >> >> new >> >> >> > home and update the link. >> >> >> >> >> >> >> >> >> We should generate new documentation and update the link >> >> >> >> >> >> >> >> >> >> >> >> > >> >> >> > I'll see if I can setup automating Lucene.Net <http://lucene.net> >> >> nuget >> >> >> > package creation for trunk in the next day or so. >> >> >> > >> >> >> > - Michael >> >> >> > >> >> >> > On Tue, Sep 20, 2011 at 5:48 PM, Prescott Nasser < >> >> geobmx...@hotmail.com >> >> >> >wrote: >> >> >> > >> >> >> > > Hey all seems like we are set with 2.9.4? Feedback has been >> positive >> >> >> and >> >> >> > > its been quiet. Do we feel ready to vote for a new release? >> >> >> > > >> >> >> > > -Prescott >> >> >> > > >> >> >> > > Sent from my Windows Phone >> >> >> >> >> > >> >> >> > >> >
