Change Presentation Style after DocProject creation

Topics: Bugs, Conceptual Topics, Extensibility, General Discussion
Feb 20, 2009 at 11:06 AM
Hi,

im looking for an easy way to change the presentation style after i created a project. MAML offers the option to exchange the look & feel of code and conceptual documentation easily, so why does Doc Project prevent this feature from being used? It is very annoying to create a new project just because changing the presentation style.

Well, however, i tired anyway to create a new project and i used the import from project feature of the DocProject Wizard. But when importing the project it failed with following error:

The imported Project "D:\ Microsoft.CSharp.targets" was not found.Confirm that the path and file exists on ... .

I browsed for the project and it is there. What am i doing wrong here?

Thx in advance

Greetings Marc Baltar
Feb 20, 2009 at 2:46 PM
Hi Marc,

Choosing a different Sandcastle presentation style for an existing DocProject or DocSite would almost be like creating a new project, which is why you have to create a new project to do so :)

I think somebody had already reported this as a limitation and I said that I'd look into it, but I can't say for sure whether it will be worth the effort to add a feature like this.  Also, and I may have written this before, I just don't see the benefit - I choose a style that I want and stick with it (that style is always VS2005 for me).  But if a different style becomes desirable at a later time, I feel that creating a new project and using the Import feature is perfectly reasonable in order to have all of the advantages that you get from DocProject's project model; e.g., you can freely modify any style on a per-project basis, it's much closer to the paradignms followed by continuous integration, it's a way to version-control Sandcastle (albeit it does make it harder to upgrade an existing project to newer versions - but Import helps out there again), it makes the styles more accessible via Solution Explorer, it makes DocProjects and DocSites feel more like specialized Visual Studio projects instead of loose wrappers for Sandcastle, and I'm sure more reasons that I'm just not remembering.  My point is that I'm not willing to trade in all of these features just to be able to choose a different presentation style without creating a new project.

However, I do understand your point about MAML.  But the fact that you can reuse the MAML topics with different styles is their advantage over HTML, regardless of whether or not DocProject allows this within a single project.  That being said, I believe there's a very popular Sandcastle automation tool that will let you change the selected Sandcastle presentation style without creating a new project, so I recommend checking it out if you haven't already: Sandcastle Help File Builder

As for the error, would you mind sending me the complete stack trace?  You can look in the Application event log for error events with DocProject as the source.  My initial impression is that an MSBuild property such as, MSBuildBinPath or MSBuildToolsPath, is not being resolved.

Thanks,
Dave
Feb 20, 2009 at 2:57 PM
Related work item:
http://www.codeplex.com/DocProject/WorkItem/View.aspx?WorkItemId=16938
Feb 20, 2009 at 4:09 PM
Hi dave,

ok. I think about the presentation style more of a property of the project that you can change easily and that is transparent to version control.

Regarding the error: I searched in the event log, there are entries from docproject but there is no entry regarding the project import.


Feb 20, 2009 at 8:46 PM
Hi,

What version of Visual Studio are you using and what version of the .NET Framework does your project target?
What property does the path to the Microsoft.CSharp.targets file contain (it should be one of the properties that I mentioned in my first response)?
Are you perhaps trying to import an older project that was built pre-.NET 3.5 into a .NET 3.5 project?

Try changing it to the other property in the source project and then try importing again; e.g., change MSBuildToolsPath to MSBuildBinPath.  Or just try hard-coding the full path :)

- Dave
Feb 20, 2009 at 8:56 PM
Edited Feb 20, 2009 at 8:58 PM
Hi  Marc,

> I think about the presentation style more of a property of the project that you can change easily and that is transparent to version control.

98% of the files that you see under the Help folder in your project are imported directly from Sandcastle, and only a handful are modified by DocProject.  So in DocProject, a presentation style is not merely a property, it is the project.

I think SHFB works more like how you think of projects, which is why I recommended that you take a look at it.  There are obviously different opnions on this subject, which is why it's great that there's a choice of documentation tools nowadays.

- Dave
Feb 25, 2009 at 4:43 PM
hi dave,

im using the Visual Studio Team System 2008 with visual studio version 9.0.21033.8. And nope im trying to import a .NET 3.5 SP1 project into a .NET 3.5 SP1 project.

Could you explain this a a little more in detail. I don't have any knowledge of Microsofts build process. How can i hardcode the path?

Thx in advance.
Feb 25, 2009 at 6:14 PM
Hi Marc,

> The imported Project "D:\ Microsoft.CSharp.targets" was not found.Confirm that the path and file exists on ...

This appears to be an MSBuild error, although I can't repro.  The specified path indicates to me that some MSBuild property wasn't resolved during the import process.  The unresolved property is most likely either $(MSBuildToolsPath) or $(MSBuildBinPath).  In a text editor, open up the source project file (e.g., .csproj, .vbproj) that you are trying to import and locate an element similar to <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />.  As in my example, you should find one of the aforementioned properties as part of the Project path.  Swap it with the other property and then save the project and try importing it again.  Alternatively, hard-code the path to Microsoft.CSharp.targets instead of using either of the properties (on my system it's under, C:\Windows\Microsoft.NET\Framework\v3.5\).

- Dave
Feb 26, 2009 at 10:37 AM
But i tried to import a docproject. Docproject uses .vbproj files so why does the import wizard demand a Microsoft.CSharp.targets file. 
I have allready been looking for "Microsoft.CSharp.targets" but its a vbproj so there is only a line with Microsoft.VisualBasic.targets.
 
Feb 26, 2009 at 12:11 PM
Hi Marc,

Well I didn't know that your source project is a VB.NET DocProject.  That's a different story :)

If you'd like to send the source project to me I can try to reproduce the problem.  Send me your email address and I'll respond with mine so that you can send me the project, zipped.

- Dave
Feb 26, 2009 at 1:23 PM
Hi dave,

i cant send you the project, it's a confidential company project ;-).  Can't you just create a vb.net docproject and check this. Why is the wizard thinking that it is a csharp docproject ? That seems the problem! What can i do?


Greetings

marc
Feb 26, 2009 at 2:53 PM
Hi Marc,

I can't repro the error.  It might be helpful if you provided a list of steps.  Here's what I tried:

1. Create a new VB.NET DocProject
2. Create a new VB.NET DocProject and on the Import step of the New Project Wizard, enter the path to the previous DocProject.
3. Create a new C# DocProject and on the Import step of the New Project Wizard, enter the path to the first DocProject.

All three projects were created successfully.

- Dave
Feb 27, 2009 at 10:30 AM
Hi dave,

i found the problem now. You can reproduce the error with the following steps:

* create a solution
* create a normal c# project in the solution (not a c# docproject project !!!)
* create now a vb docproject and choose at the last step of the doproject wizard (which is the choos sources dialog) the c# project to use it as reference to be documented.
* create now a vb docproject and import the vb docproject which will trigger the error.

I have seen not seen any difference between a c# docproject and a vb docproject so i have choosen a vb docproject for documenting the code of a c# project because simply i have found it  first.
Apparently the language of the docproject and the project which contains the code to be documented have to match.

What can i do now to import the project anyway ?

Greetings

marc
Feb 27, 2009 at 10:33 AM
By the way it doesnt helps to create a c# docproject and then import my vb docproject.
Mar 2, 2009 at 3:30 PM
Help! I need somebody!  Help! Not just anybody! Help! You know I need someone! Help! ...


Mar 2, 2009 at 6:57 PM
Hi Marc,

I haven't had time to repro the problem yet, let alone find a solution.  You'll just have to be patient until I respond or else work out the problem for yourself  :)

- Dave
Mar 5, 2009 at 1:20 PM
Edited Mar 5, 2009 at 1:22 PM
Hi Marc,

The error message is actually referring to the referenced C# project, which is why it states Microsoft.CSharp.targets.

The problem appears to be that the referenced C# project (I created a standard Class Library project for my test) is using $(MSBuildToolsPath).  Opening the .csproj file and changing the <Import /> to use $(MSBuildBinPath) instead will allow you to specify the first VB DocProject as an import for the second.

Apparently this issue only affects DocProjects that are in one language but reference a source project in another.  (I was able to repro using your steps and reversing the project languages.)

At this time I don't know why MSBuild cares about whether MSBuildToolsPath or MSBuildBinPath is used, and I find it especially strange that it doesn't care when the DocProject and its sources use the same language.

I'll add a workitem for this and fix it for 1.12.0.

Thanks, 
Dave
Mar 5, 2009 at 1:27 PM
Thx!

Greetings

marc
Mar 5, 2009 at 1:36 PM
Work item:
http://docproject.codeplex.com/WorkItem/View.aspx?WorkItemId=21506