DocProject for Sandcastle

New Post: no summary, param, remarks, etc. in the generated chm file

bobbyfu — Thu, 19 Nov 2009 23:00:42 GMT

Hi Dave,

I got it. I was looking at a class with no summary. Thanks. Nice tool.

- Bobby

New Post: no summary, param, remarks, etc. in the generated chm file

bobbyfu — Thu, 19 Nov 2009 22:49:26 GMT

Thanks Dave for pointing out my mistake. I enabled the XML document output for the source project, rebuilt the entire solution (including the DocSite). The /// <summery> tag and other tags are still not showing up in the CHM file and in the HTM files.

What's else I forget? Thanks.

- Bobby

New Post: Progress Status of your MAML-Editor

davedev — Thu, 19 Nov 2009 15:07:18 GMT

Hi Michael,

I work on it when I can find the time. I've been on a crazy project and work schedule for several months now, so that isn't helping either :) Also, I've begun updating DocProject to support Visual Studio 2010, so that's going to take up a couple of months as well.

You may want to take a look at DocTools in the mean time. I haven't tried it myself, but I suspect that it produces HTML output. If you could somehow configure it to save the HTML into the Help\Topics\HTML\ folder of your DocProject or DocSite, then you can import the HTML files into Topic Explorer and build your documentation as normal.

Of course, I recommend MAML over HTML, but without a nice WYSIWYG experience you may prefer the DocTools approach for now.

Alternatively, you could have the team author HTML topics in Visual Studio using the built-in HTML designer. It works well with CSS references too, so that might make it a bit easier to keep the documents uniform without having all of the benefits that MAML provides.

- Dave

New Post: Obsolete methods/classes/properties

davedev — Thu, 19 Nov 2009 14:52:24 GMT

Hi,

What versions of DocProject and Sandcastle are you using?

It's working for me. In the list topics (such as Types and Members) there's text that reads, "Obsolete.". It renders in red and appears next to types and members that are marked with System.ObsoleteAttribute in code.

It seems that the output of the MRefBuilder program includes the message argument as well. I was able to improve the documentation by updating the XSL a bit so that it includes the message value. To do that, and also to verify whether your XSL files are the same as mine, follow these steps:

Open your project's Help\Presentation\Style\Transforms\utilities_reference.xsl file.
1. Alternatively, you can make the necessary changes directly to the file in Sandcastle's installation folder so that it applies to all new DocProjects and DocSites.
Find all occurrences of the following sequence of elements:

<xsl:text> </xsl:text> <include item="obsoleteRed" />

Replace each occurrence with the following element:

<xsl:call-template name="obsolete" />

At the bottom of the file, before the closing </xsl:stylesheet> tag, insert the following XSL:

 <xsl:template name="obsolete"> <xsl:text> </xsl:text> <include item="obsoleteRed" /> <xsl:if test="normalize-space(attributes/attribute[type/@api='T:System.ObsoleteAttribute']/argument/value)"> <xsl:value-of select="attributes/attribute[type/@api='T:System.ObsoleteAttribute']/argument/value" /> </xsl:if> </xsl:template>

Let me know if you still need assistance.

- Dave

New Post: Progress Status of your MAML-Editor

MyKey0815 — Thu, 19 Nov 2009 13:35:17 GMT

Hello Dave,

for a long time ago you write about a MAML-Editor. I want to ask you what is the status of the Editor? Is it possible that you send me a Beta-Version of your application? I´m using your DocProject 1.11.0 in a huge application. Someone of my Teammembers should assit me to make the documentation but he didn´t familiry with HTML, Tags and so one. I think it would be a big help for me and him, if I can use your Editor.

Thanks for your answer

Michael

New Post: no summary, param, remarks, etc. in the generated chm file

davedev — Thu, 19 Nov 2009 02:35:41 GMT

Hi Bobbyfu,

You've almost got it right. You have to enable XML documentation output for the source projects, not the DocSite project.

DocProject gathers all of the XML documentation output from each of the source projects and passes them to Sandcastle. The XML documentation output for the DocSite project itself, if you've enabled it, is entirely ignored.

- Dave

New Post: no summary, param, remarks, etc. in the generated chm file

bobbyfu — Thu, 19 Nov 2009 01:16:30 GMT

Additional information.

1. I have enabled generating XML Document option from the DocSite project. The XML file is in the bin\DocSite.XML.

2. DocProject version is 1.11.0.0 and Sandcastle is 2.4.10520.1

Now what?

New Post: no summary, param, remarks, etc. in the generated chm file

bobbyfu — Thu, 19 Nov 2009 00:13:30 GMT

Hi,

I finally get the Sandcastle and DocProject working in the Visual Studio 2008. The CHM file or the web site (DocSite) is generated. But there is a small problem. None of the class, property, or method has summary, param, remarks that I added in my C# source code with /// <summary> <param> or <remarks>.

Is there anything missing in my configuration file? Please help.

Best,

bobbyfu

New Post: DocProject projects in Team Build definition

Vossekop — Fri, 13 Nov 2009 21:53:07 GMT

I have never found a resolution for the problem, and i since moved to another documentation solution (also not running them during builds).

New Post: DocProject projects in Team Build definition

_Trip — Thu, 12 Nov 2009 17:11:19 GMT

Bummer - I've just run across this exact same issue. As soon as the Docs project completes its processing, it doesn't move on to the next item in the process (in my case, it just isn't running the "AfterDropBuild" items it needs to in order for my copy to work on my published site.

Has there been any others with this issue? I can't seem to find a resolution on the Net anywhere.

Tim

New Post: Obsolete methods/classes/properties

nomy — Tue, 10 Nov 2009 23:00:14 GMT

I'm marking classes/methods/properties as obsolete using the ObsoleteAttribute in my source code. I would like similar behavior to the MSDN documentation, where obsolete methods/classes/properties are clearly shown using red text.

Unfortunately, this just doesn't happen for me. I've checked the XML output from VisualStudio, and it looks like this XML is feeding the appropriate obsolete markers into DocProject/Sandcastle... but I'm not getting anything in the CHM to suggest that stuff is being marked as obsolete.

Any ideas/suggestions?

Updated Wiki: Documentation

davedev — Tue, 27 Oct 2009 17:02:24 GMT

About DocProject
Overview of DocProject as an open source project and a list of its features.
Latest Release Notes
Please read this document carefully before attempting to install DocProject.
Sandcastle Help
Provides important notes and links to various online resources for learning more about Microsoft's Sandcastle tools.
- Sandcastle and Proxy Servers
- Information about using proxy server configurations with Sandcastle.
Sandcastle Build Component Templates
Visual Studio Item Templates for creating custom Sandcastle build components that can take advantage of editor support in automation tools such as DocProject.
ResolveExternalLinksComponent
Provides documentation for ResolveExternalLinksComponent, which is a Sandcastle build component that extends <see> tags by allowing IDs to be specified instead of URLs.
DocProject External UI
Provides support for configuring and building DocProjects and DocSites outside of the Visual Studio IDE (useful for Visual Studio Express users).
DocProject Components
Overview of DocProject's two major components: Visual Studio Project Templates and a Visual Studio Add-In.
DocProject Templates
DocProject templates are used to create Visual Studio projects that build compiled help for their project references and external sources.
- DocSite Templates
- DocSite templates are DocProject templates that generate Visual Studio Web Application projects.
Build Process
Information regarding the build process, steps and build types of DocProjects and DocSites.
Sandcastle Deployment Plugin
The Sandcastle/Deployment plug-in extends the Sandcastle build engine in DocProject by adding deployment features.
How To...
Guidance for performing some common tasks associated with DocProject.
- Installation and Uninstallation
- Configuration
  - How To Configure Visual Studio 2005 for DocProject
  - How To Configure DocProject
- Using DocProject
- Sandcastle Features in DocProject
- Usage Tutorials
- Extensibility Tutorials

Updated Wiki: Documentation

davedev — Tue, 27 Oct 2009 17:02:13 GMT

Home Page

About DocProject
Overview of DocProject as an open source project and a list of its features.
Latest Release Notes
Please read this document carefully before attempting to install DocProject.
Sandcastle Help
Provides important notes and links to various online resources for learning more about Microsoft's Sandcastle tools.
- Sandcastle and Proxy Servers
- Information about using proxy server configurations with Sandcastle.
Sandcastle Build Component Templates
Visual Studio Item Templates for creating custom Sandcastle build components that can take advantage of editor support in automation tools such as DocProject.
ResolveExternalLinksComponent
Provides documentation for ResolveExternalLinksComponent, which is a Sandcastle build component that extends <see> tags by allowing IDs to be specified instead of URLs.
DocProject External UI
Provides support for configuring and building DocProjects and DocSites outside of the Visual Studio IDE (useful for Visual Studio Express users).
DocProject Components
Overview of DocProject's two major components: Visual Studio Project Templates and a Visual Studio Add-In.
DocProject Templates
DocProject templates are used to create Visual Studio projects that build compiled help for their project references and external sources.
- DocSite Templates
- DocSite templates are DocProject templates that generate Visual Studio Web Application projects.
Build Process
Information regarding the build process, steps and build types of DocProjects and DocSites.
Sandcastle Deployment Plugin
The Sandcastle/Deployment plug-in extends the Sandcastle build engine in DocProject by adding deployment features.
How To...
Guidance for performing some common tasks associated with DocProject.
- Installation and Uninstallation
- Configuration
  - How To Configure Visual Studio 2005 for DocProject
  - How To Configure DocProject
- Using DocProject
- Sandcastle Features in DocProject
- Usage Tutorials
- Extensibility Tutorials

Updated Wiki: Wikimap

davedev — Tue, 27 Oct 2009 17:01:28 GMT

Wikimap

Home Page

About DocProject
Overview of DocProject as an open source project and a list of its features.
Latest Release Notes
Please read this document carefully before attempting to install DocProject.
Sandcastle Help
Provides important notes and links to various online resources for learning more about Microsoft's Sandcastle tools.
- Sandcastle and Proxy Servers
- Information about using proxy server configurations with Sandcastle.
Sandcastle Build Component Templates
Visual Studio Item Templates for creating custom Sandcastle build components that can take advantage of editor support in automation tools such as DocProject.
ResolveExternalLinksComponent
Provides documentation for ResolveExternalLinksComponent, which is a Sandcastle build component that extends <see> tags by allowing IDs to be specified instead of URLs.
DocProject External UI
Provides support for configuring and building DocProjects and DocSites outside of the Visual Studio IDE (useful for Visual Studio Express users).
DocProject Components
Overview of DocProject's two major components: Visual Studio Project Templates and a Visual Studio Add-In.
DocProject Templates
DocProject templates are used to create Visual Studio projects that build compiled help for their project references and external sources.
- DocSite Templates
- DocSite templates are DocProject templates that generate Visual Studio Web Application projects.
Build Process
Information regarding the build process, steps and build types of DocProjects and DocSites.
Sandcastle Deployment Plugin
The Sandcastle/Deployment plug-in extends the Sandcastle build engine in DocProject by adding deployment features.
How To...
Guidance for performing some common tasks associated with DocProject.
- Installation and Uninstallation
- Configuration
  - How To Configure Visual Studio 2005 for DocProject
  - How To Configure DocProject
- Using DocProject
- Sandcastle Features in DocProject
- Usage Tutorials
- Extensibility Tutorials

Updated Wiki: Documentation

davedev — Tue, 27 Oct 2009 17:01:10 GMT

Documentation

Commented Issue: 'value cannot be null' when adding new DocProject [19314]

davedev — Thu, 08 Oct 2009 01:20:34 GMT

Symptom:
The following occurs when adding a new DocProject project to a solution.
---
An error occurred while running the New Project Wizard:
System.ArgumentNullException: Value cannot be null.
Parameter name: path2
at System.IO.Path.Combine(String path1, String path2)
at DaveSexton.DocProject.VCProjectOutput.get_OutputFile()
at DaveSexton.DocProject.ProjectFactory.IsSourceProject(IAnyProject project)
at DaveSexton.DocProject.Wizards.ChooseSourcesStep.<get_SourceProjects>b__0(IAnyProject currentProject)
at DaveSexton.DocProject.DocProjectEnvironment.<FindProjectsInternal>d__7.MoveNext()
at DaveSexton.DocProject.MarshalByRefEnumerator`1.MoveNext()
at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
at DaveSexton.DocProject.Wizards.ChooseSourcesStep.get_SourceProjects()
at DaveSexton.DocProject.Wizards.ChooseSourcesStep.get_Control()
at DaveSexton.DocProject.Wizards.ChooseSourcesStep.GetUserInterface(WizardController controller, Boolean preloading)
at DaveSexton.DocProject.Wizards.Foundation.WizardStep.GetUserInterfaceInternal(WizardController controller, Boolean preloading)
at DaveSexton.DocProject.Wizards.Foundation.WizardController.<Start>b__0(WizardStep step)
at DaveSexton.DocProject.Wizards.Foundation.WizardController.ForEachStep(Action`1 action)
at DaveSexton.DocProject.Wizards.Foundation.WizardController.Start(Boolean moveToVisible)
at DaveSexton.DocProject.Wizards.Foundation.WizardForm..ctor(String wizardName, WizardStep firstStep, WizardStep lastStep)
at DaveSexton.DocProject.Wizards.DocProjectConfigurationWizard.Run(IDocProject project, EventHandler`1 errorHandler)
at DaveSexton.DocProject.Wizards.VSWizard.ProjectFinishedGenerating(Project project)
---

Reproduction Steps:
1. VS2005, DocProject 1.11.0 (June 8 2008)
2. Create a new solution.
3. Add a new project of type: OtherLanguages -> Visual C++ -> General -> Makefile project
4. In the project properties, set the property; Configuration Properties -> NMake -> General -> Output to be empty.
5. Add a new DocProject project to the solution.
6. Fails with above message.

Notes:
We sometimes use projects like this for custom build steps, e.g. deploying a set of dlls, where there is no single output file.
Comments: ** Comment from web user: davedev **

Thanks for reporting your scenario. Note that the error occurs during the New Project Wizard, which VS starts after the project is created. If the New Project Wizard doesn't complete successfully then you will be left with a project that is an unknown state, hence the error when you try to open DocProject Properties for the corrupted project.

The initial error occurrs when a project does not define an output file. (See step #4 in the OP's repro instructions.) If you have a project of a supported project type (e.g., class library or application project in C#, VB.NET or C++/CLR) in your solution that does not produce an output file then it's not compatible with DocProject 1.11.0. This is because DocProject expects all projects of supported types to produce output and may fail otherwise. I'll probably just elliminate projects without any output from the list of sources in the Choose a Source step of the New Project Wizard (instead of crashing :). The source code is available if you don't want to wait until I can find the time...

How To Use the Source Code
http://docproject.codeplex.com/Wiki/View.aspx?title=How%20To%20Use%20The%20Source%20Code

New Post: A property cannot be set while building

davedev — Sat, 03 Oct 2009 15:52:52 GMT

This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.

Created Issue: A property cannot be set while building [24796]

davedev — Sat, 03 Oct 2009 15:52:51 GMT

Original discussion:
http://docproject.codeplex.com/Thread/View.aspx?ThreadId=69397

I found a way to make the problem disappear by changing some DocProject properties and excluding some files from the project.

I changed the "Include Project Output Dialog" settings to the following:Apply to all default: TrueInclude project output default: FalseDon't ask me this again: True

Next i excluded the "/bin" folder, the "/Help/html" and all the non folder items in "/Help" folder from the project.I also deleted these files and folders from the filesystem itself, but i don't think this was really needed as DocProject just puts them back and nothing bad comes from that.

It won't add the generated content to the project anymore now, but i actually like it that way so for me theres no problem there.

New Post: A property cannot be set while building

davedev — Sat, 03 Oct 2009 15:47:03 GMT

Hi Jan-Peter,

Thanks for following-up with this. From your analysis it seems that the issue is caused when build output is included as project items that appear in Solution Explorer.

I'll try to repro again when I get some time and see if I can fix the problem.

Thanks,
Dave

Commented Issue: 'value cannot be null' when adding new DocProject [19314]

Charlie47 — Fri, 02 Oct 2009 21:05:20 GMT

I'm getting the same error, but under slightly different circumstances.

I'm using Visual Studio 2008, XP SP2, DocProject 1.2.0.0, Sandcastle 2.4.10520, updated with the styles patch (http://www.codeplex.com/SandcastleStyles), I'm running as adminstrator, The variable DXROOT only exists in the System variables and is set to D:\XP Program Files\Sandcastle\, which is where I installed Sandcastle (I have never had either Sandcastle or DocProject on this machine before).

I have an existing solution to which I try to add a DocProject project, by choosing "Add/New Project" from the Solution Explorer,and then choosing DocProject as the project and DocProject as the template.

The DocProject gets created before the error occurs. If I choose "DocProject Properties" from solution explorer I get another error "The DocProject1 project is missing the name of the Sandcastle presentation style that it uses...".

I don't know how to proceed at this point. I'm down to trying various ways to start DocProject to see if I can get anything to work.