First pass at API documentation...

[Jon Skeet]

I've just committed the first build of the API docs:

http://morelinq.googlecode.com/hg/docs/api/Index.html

There's now a builddocs.bat batch file at the top level which builds the Release build and then runs Sandcastle Helpfile Builder (which obviously you have to have installed). It's rough and ready, but gets the job done. While I don't really like having generated artefacts in source control (and having to remember to build and commit it explicitly) it does make life easier for having reasonably "live" docs, and provides a natural branching strategy too.

Next up, continuous builds...

Jon

[Atif Aziz]

Jon, wouldn't it be better to separate out the generated docs in a new repo instead of using the default one? This way, the generated docs won't pollute or bloat the base code repo. Good thing is that GCPH allows one to house multiple Hg repos under one project.

- Atif

Jon

--
You received this message because you are subscribed to the Google Groups "MoreLINQ Developers" group.
To post to this group, send email to moreli...@googlegroups.com.
To unsubscribe from this group, send email to morelinq-dev...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/morelinq-dev?hl=en.

[Jon Skeet]

On 11 June 2012 21:03, Atif Aziz <aziz...@gmail.com> wrote:

Jon, wouldn't it be better to separate out the generated docs in a new repo instead of using the default one? This way, the generated docs won't pollute or bloat the base code repo. Good thing is that GCPH allows one to house multiple Hg repos under one project.

I don't think it'll be an issue - the generated content is all under its own subdirectory (docs/api, deliberately two levels deep in case we also want a user guide, which is what I've done in Noda Time), and it's a pretty tiny repository.

The advantage of this over two repos is that we get separate sets of docs for separate branches for free, instead of having to remember to branch in two places and switch between branches in two places too.

It certainly hasn't been a problem in Noda Time.

Jon

[Johannes Rudolph]

Next up, continuous builds... 

Speaking of Continous Integration, which service are you planning to set up? I can offer some input on TeamCity (teamcity.codebetter.com) as well as some minor MSBuild work. Certainly not a guru, but would be happy to help in case issues arise.

--

[Jon Skeet]

TeamCity was indeed going to be my plan... shouldn't be too hard given that it's just building a solution and running unit tests.

Jon

[Johannes Rudolph]

jup, TC makes that rather easy. You may look into  https://bitbucket.org/johannesrudolph/subspec/src  for some inspiration. Until rev  a35fcc8ae1f6  it did also build a real dll + NuGet package. Today it's just a single internal .cs file with less than 500 lines.

[Atif Aziz]

I get the benefit of branching for docs but my point was to use a separate repo just for the generated bits. What needs to be tracked and versioned with branching and/or tagging is the build scripts, templates other bits needed needed to generate the docs.

 

Also, unless we have identical environments, I see building of the docs producing differences that seem unaccountable to the SHFB uninitiated (like me). I believe I just ran builddocs on the same code but the hg status showed up a lot of changed files (see list below), some new ones (unignored and to do with PHP) and one that's gone missing (docs\api\html\R_Project.htm).I installed and used SHFB 1.9.4.0. For me, and ideally, if nothing has changed in the code then the docs should reflect that.

 

M docs\api\Index.html
M docs\api\TOC.js
M docs\api\html\M_MoreLinq_MoreEnumerable_AssertCount__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_AssertCount__1_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Batch__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Batch__2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Concat__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Concat__1_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Consume__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_DistinctBy__2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_DistinctBy__2_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_EquiZip__3.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ExceptBy__2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ExceptBy__2_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ForEach__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_GenerateByIndex__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Generate__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_GroupAdjacent__2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_GroupAdjacent__2_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_GroupAdjacent__3.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_GroupAdjacent__3_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Index__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Index__1_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_MaxBy__2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_MaxBy__2_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_MinBy__2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_MinBy__2_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Pad__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Pad__1_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Pad__1_2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Pairwise__2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Pipe__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_PreScan__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Prepend__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Scan__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_SingleOrFallback__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_SkipUntil__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__1_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__1_2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__1_3.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__1_4.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__1_5.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__2_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__2_2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__2_3.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__2_4.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Split__2_5.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_TakeEvery__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_TakeLast__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_TakeUntil__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ToDataTable__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ToDataTable__1_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ToDataTable__2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ToDataTable__2_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ToDelimitedString__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ToDelimitedString__1_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ToHashSet__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ToHashSet__1_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Trace__1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Trace__1_1.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Trace__1_2.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_ZipLongest__3.htm
M docs\api\html\M_MoreLinq_MoreEnumerable_Zip__3.htm
M docs\api\html\M_MoreLinq_SequenceException__ctor.htm
M docs\api\html\M_MoreLinq_SequenceException__ctor_1.htm
M docs\api\html\M_MoreLinq_SequenceException__ctor_2.htm
M docs\api\html\M_MoreLinq_SequenceException__ctor_3.htm
M docs\api\html\N_MoreLinq.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_AssertCount.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_Batch.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_Concat.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_DistinctBy.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_ExceptBy.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_GroupAdjacent.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_Index.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_MaxBy.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_MinBy.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_Pad.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_Split.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_ToDataTable.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_ToDelimitedString.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_ToHashSet.htm
M docs\api\html\Overload_MoreLinq_MoreEnumerable_Trace.htm
M docs\api\html\Overload_MoreLinq_SequenceException__ctor.htm
M docs\api\html\T_MoreLinq_MoreEnumerable.htm
M docs\api\html\T_MoreLinq_SequenceException.htm
M docs\api\styles\presentation.css
! docs\api\html\R_Project.htm
? docs\api\FillNode.php
? docs\api\LoadIndexKeywords.php
? docs\api\SearchHelp.inc.php
? docs\api\SearchHelp.php
? docs\api\html\R_Project_Help.htm
? docs\api\index.php

 

- Atif

--

[Jon Skeet]

On 12 June 2012 20:43, Atif Aziz <aziz...@gmail.com> wrote:

I get the benefit of branching for docs but my point was to use a separate repo just for the generated bits. What needs to be tracked and versioned with branching and/or tagging is the build scripts, templates other bits needed needed to generate the docs.

No, I disagree - I'd want to have the generated docs for each branch reflecting the content for that branch. So the 1.0 docs will go under a URL with 1.0 etc, without us having to be careful about it (beyond remembering to regenerate them in the first place). I think it's a lot less error prone, even though it does mean having generated artefacts in the main repo.

 

Also, unless we have identical environments, I see building of the docs producing differences that seem unaccountable to the SHFB uninitiated (like me). I believe I just ran builddocs on the same code but the hg status showed up a lot of changed files (see list below), some new ones (unignored and to do with PHP) and one that's gone missing (docs\api\html\R_Project.htm).I installed and used SHFB 1.9.4.0. For me, and ideally, if nothing has changed in the code then the docs should reflect that.

Hmm. Almost certainly an SHFB version difference. My version is 1.9.3.0, so that probably explains it.

Normally rebuilding with the same version of SHFB doesn't create any changes. Is 1.9.3.0 available so you could try it and see whether you get the same result?

Jon

[Atif Aziz]

OK, I can live generated docs in the default/main repo for now. :) I've also tested with SHFB 1.9.3.0 and the results are much better. I only get one changed files now:

 

M docs\api\html\T_MoreLinq_SequenceException.htm

 

I quickly looked through to see what's changed and it seems like something from the XML doc summary. It looks like the documentation of the inherited members from Object are different, and fortunately for now, SequenceException is the only public non-static class in the project otherwise all other files would've showed changes too.

 

Are you planning to upgrade to 1.9.4.0 soon?

 

- Atif

--

[Jon Skeet]

On 12 June 2012 21:23, Atif Aziz <aziz...@gmail.com> wrote:

OK, I can live generated docs in the default/main repo for now. :) I've also tested with SHFB 1.9.3.0 and the results are much better. I only get one changed files now:

 

M docs\api\html\T_MoreLinq_SequenceException.htm

 

I quickly looked through to see what's changed and it seems like something from the XML doc summary. It looks like the documentation of the inherited members from Object are different, and fortunately for now, SequenceException is the only public non-static class in the project otherwise all other files would've showed changes too.

Interesting. I wonder why.

  

Are you planning to upgrade to 1.9.4.0 soon?

Hadn't planned on it, but could do. Haven't looked at the version history to see what the benefits are.

Jon