A noviece questions

Topics: General Questions
Jul 10, 2008 at 2:06 PM
Edited Jul 10, 2008 at 2:07 PM
Hi,

I want to use DocProject for a solution containing about 30 dll's. Some of them represent common functionalities, other are plugins or applications. Could someone help me with issues I'm getting?
1. I've decided to create one DocProject for each dll. How can I merge those HxS files to create one package for VS2005 Documentation viewer? I've tried "FAR" from "Helpware" but without much luck.
2. I would like to categorize them by purpose (plugins, common etc) can I do it by configuring DocProject or do I need to do it while merging those help files in next step using some other tool?
3. My help files do not reference each other (types, definitions), I'm probably missing some basic step but find a solution. Could someone give me a hint?

Thanks in advance

Coordinator
Jul 10, 2008 at 3:07 PM
Hi, 

1. I've decided to create one DocProject for each dll. How can I merge those HxS files to create one package for VS2005 Documentation viewer?  I've tried "FAR" from "Helpware" but without much luck.

DocProject does not yet support this scenario itself.  I'm pretty sure that HxS supports merging though - I think you'd need to create a master collection definition file that groups the .HxS files together.  (Note that I haven't tried this myself.)

See the following articles for more information: 

Collection-Level File Overview
http://msdn.microsoft.com/en-us/library/bb165635.aspx

MS H2 Collection Tutorial, §3.  Collection-Level Files
http://www.helpware.net/mshelp2/h2tutorial.htm

Also see this related work item:  

DocTemplate/DocSite Master linking several projects together

2. I would like to categorize them by purpose (plugins, common etc) can I do it by configuring DocProject or do I need to do it while merging those help files in next step using some other tool?


I believe that you can categorize the TOC in which the .HxS files will be merged using the collection-level .HxT file.

3. My help files do not reference each other (types, definitions), I'm probably missing some basic step but find a solution. Could someone give me a hint?

I think you need to run Sandcastle's MRefBuilder.exe program on all of your assemblies to generate reflection.org files.  Then you must run the appropriate doc style transformation (from Sandcastle's ProductionTransforms folder - most likely ApplyVSDocModel.xsl) on each reflection.org file to generate reflection.xml files.  Then register each of the reflection.xml files in the ResolveReferenceLinksComponent2 confiruation in the Help 2.x stacks in each of your projects.  (Help\Presentation\Style\Configuration\sandcastle.help2x.config, conceptual.help2x.config).

Also see the following discussion: 

Sandcastle: How do I create seealso links to external Hxs files
http://forums.msdn.microsoft.com/en/devdocs/thread/fd00d597-7310-4aed-9072-be5438843a6e/

Note that you can add the new target elements to the configuration files manually or via the build component stack editors.  More information about the editors can be found in this article: 

How To Use Third-Party Build Components In DocProject
http://www.codeplex.com/DocProject/Wiki/View.aspx?title=How%20To%20Use%20Third-Party%20Build%20Components%20In%20DocProject

- Dave
Jul 22, 2008 at 11:51 AM
I have tried creating child projects but those projects need to be recompiled to another HxS file before attaching in parent HxT. I wanted to avoid this step and for me the most suitable solution was to nest HelpTOCNode nodes. That of course solved also the problem of categorizing help topics.
What bothers me still is reference resolving for the cref links. Though recompiling reflection.org files and adding reflection.xml files helps, moreover those files don't need to be recompiled manually, because they are already being created each time DocProject projects are recompiled and are stored inside &(ProjectDir)buildhelp\reflection.xml, I still need to add all reflection.xml files manually to "Help build component stack", and set build order for DocProjects. Is there a way to add references from one DocProject to another to reference those files? If not, then what other suggestions would you have for me?
Coordinator
Jul 22, 2008 at 5:25 PM
Hi,

> Is there a way to add references from one DocProject to another to reference those [reflection.xml] files?

That's not supported yet but it should be part of the following work item:

DocTemplate/DocSite Master linking several projects together

It's a simple requirement though and you may be able to do it yourself for now through extensibility.

  1. In your DocProject or DocSite add references to System.Xml from the .NET tab and DaveSexton.DocProject.Sandcastle.dll from the Browse tab (found in DocProject's installation bin folder).
  2. Open your project's BuildProcess.cs|vb file
  3. Add using or Imports directives for System.Xml and DaveSexton.DocProject.Sandcastle.
  4. Add the following (C#) methods to the BuildProcess class.  Then add a call to ImportReflectionFiles(BuildContext context) from the BuildStarting method.
private void ImportReflectionFiles(BuildContext context)
{
	context.TraceLine("Importing reflection files...");
	context.TraceLine();

	SandcastleBuildEngine engine = (SandcastleBuildEngine) context.Engine;
	SandcastleSettings settings = engine.Settings;
	SandcastleProjectOptions options = 
		(SandcastleProjectOptions) context.Engine.Project.Options;

	string config = System.IO.Path.Combine(
		settings.ConfigurationPath, options.Help2xConfigFileName);

	string conceptualConfig = System.IO.Path.Combine(
		settings.ConfigurationPath, options.Help2xConceptualConfigFileName);

	XmlDocument configDocument = new XmlDocument();
	configDocument.PreserveWhitespace = true;
	configDocument.Load(config);
	
	XmlDocument conceptualConfigDocument = new XmlDocument();
	conceptualConfigDocument.PreserveWhitespace = true;
	conceptualConfigDocument.Load(conceptualConfig);

	ImportReflectionFiles(context, configDocument, conceptualConfigDocument);

	configDocument.Save(config);
	conceptualConfigDocument.Save(conceptualConfig);
}

private void ImportReflectionFiles(BuildContext context, params XmlDocument[] configDocuments)
{
	foreach (ISourceProject source in context.Engine.Project.ProjectSources)
	{
		context.TraceLine("Analyzing source: " + source.Name);

		IAnyProject project = source as IAnyProject;

		if (project != null && IsDocProject(project))
		{
			context.TraceLine("Found source DocProject: " + project.FilePath);

			string reflectionFile = System.IO.Path.Combine(
				project.Directory, @"buildhelp\assembler\reflection.xml");

			context.TraceLine("Importing reflection file: " + reflectionFile);

			foreach (XmlDocument config in configDocuments)
				ImportReflectionFile(context, reflectionFile, config);
		}
	}
}

private void ImportReflectionFile(BuildContext context, string reflectionFile, XmlDocument config)
{
	foreach (XmlNode component in config.SelectNodes(
		"//component[starts-with(@type, 'Microsoft.Ddue.Tools.ResolveReferenceLinksComponent')]"))
	{
		if (component.SelectSingleNode("targets[@files='" + reflectionFile + "']") == null)
		{
			XmlNode targets = component.OwnerDocument.CreateElement("targets");

			XmlAttribute files = component.OwnerDocument.CreateAttribute("files");
			files.Value = reflectionFile;
			targets.Attributes.Append(files);

			XmlAttribute type = component.OwnerDocument.CreateAttribute("type");
			type.Value = "index";
			targets.Attributes.Append(type);

			component.AppendChild(targets);
		}
	}
}

private static bool IsDocProject(IAnyProject project)
{
	XmlDocument document = new XmlDocument();
	document.Load(project.FilePath);

	XmlNamespaceManager ns = new XmlNamespaceManager(document.NameTable);
	ns.AddNamespace("msbuild", "http://schemas.microsoft.com/developer/msbuild/2003");

	XmlNode attr = document.SelectSingleNode("//msbuild:UserProperties/@IsDocProject", ns);

	bool isDocProject;
	return attr != null && bool.TryParse(attr.Value, out isDocProject) && isDocProject;
}

- Dave

Jul 28, 2008 at 11:24 AM
Thanks.
Additionally I need to add references to DocProjects to which the cref links will be resolved, but than comments from those projects will be added to documentation. Should I simply remove it by manually adding "apiFilter" tags in MRefBuilder.config file, or is there some other way to do it?
Coordinator
Jul 28, 2008 at 1:24 PM
Hi,

Actually I didn't think about that aspect when I wrote the sample code for you :)

If you don't want to use references (since you don't want the other projects included in the documentation set) then you'll have to add the references to the external reflection.xml files manually by editing the configuration files in your project's Help\Presentation\Style\Configuration folder and then set the appropriate build order in Visual Studio.  So we're back to the beginning again.

Just to be clear, the problem is that in order for DocProject to know about the other reflection.xml files dynamically you must add some type of reference at least, but the only type of reference that controls build order is a project reference, which DocProject uses to build documentation.  Handling this with any other type of reference is pointless though since you could just add the reflection.xml paths directly in the config files and control the build order using VS.

I guess the best solution might be to add the ability to choose the type of each project reference instead of assuming that they all must be included in the compiled documentation.  I could add a new project option that opens a dialog.  The dialog would list all of the project references with a drop down field for choosing a type: DocumentReference Only, Ignore.  (The last option could be useful if you wanted to use a project reference to expose APIs that your build process component will use, without building documentation for the reference.)

Does that seem like it would help in your situation?  I'll add a new work item.

- Dave
Coordinator
Jul 28, 2008 at 1:39 PM
Work item:
http://www.codeplex.com/DocProject/WorkItem/View.aspx?WorkItemId=17565
Jul 28, 2008 at 2:46 PM
Yes, I believe this would be the best option
For now I'll add reflection.xml files manually and control build order via VS.
Thanks