A few quick? questions

Topics: General Questions, Sandcastle
Jan 18, 2008 at 9:34 PM
I am new to DocProject, having only really had a quick look so far but I seem to be missing a few simple things ...

  • I am able to add the documentation output from a project during the create project wizard, but I do not see where I can either (a) add the output from additional projects to the same help files or (b) add additional namespaces from the existing project outputs if I have filtered them during the wizard.

  • I am also unable to see how I can switch off the "Send Feedback" radio button control at the bottom of each page (in VS2005 mode).

  • I cannot see how to add a root item under which the namespaces will sit and associated summary information to that node; similarly, I do not see how to add summary (and or other) text to the namespaces themselves.

  • Finally, how can I ensure that when documenting a library for the compact framework that the CF icons appear in the output (as per VS2005); I have seen that the icon exists in the 'icons' folder but cannot find the correct markup to ensure they are in the output.

Thanks for all and any help.

Martin
Jan 19, 2008 at 12:29 AM
Hi Martin,

I'll address each question individually and assume that you're using VS 2005 Standard edition or higher, DocProject 1.9.0 RC and the Sandcastle October 2007 CTP:


(a) add the output from additional projects to the same help files

DocProject supports two kinds of sources:
  • Project references: All of the available project references are listed in the last step of the New Project Wizard. Choose zero, one or more. At a later time you can add/remove project references from the project's References folder. If a project is not listed in the wizard then it's not supported by DocProject (in that case use the next option).
  • External sources: These can be managed using a dialog found in the DocProject Properties window. To open the properties window, right-mouse click your DocProject or DocSite in Solution Explorer and you should see its context menu item at the bottom. Once opened, you'll find the External sources property under the Build category. Simply click the ellipses button (...) on the right to open the dialog. The list of external sources that you choose is stored in the project file.
Note that external sources can be any managed assembly or reflection.org files generated from other tools such as AjaxDoc.


(b) add additional namespaces from the existing project outputs if I have filtered them during the wizard.

I'm not sure what you mean here. The New Project Wizard doesn't offer any filtering capabilities, and that's the only wizard :)

If you're using the API Topic Management dialog to filter namespaces then any namespaces that you exclude will not be present in the documentation. Any namespaces that you add to code in your source projects at a later time will automatically be included in the documentation, by default (unless you set up some dynamic filter to exclude them).


I am also unable to see how I can switch off the "Send Feedback" radio button control at the bottom of each page (in VS2005 mode).

As far as I know Sandcastle doesn't provide a quick and easy solution to this, but there may be a manual solution:

Disable Send Feedback

You can use DocProject's Topic Designer (also shown as a step in the New Project Wizard) to edit the feedback's shared content document but there doesn't seem to be any combination of settings that successfully removes the control (although I haven't played around with it that much). Ideally, you should be able to set some content item to false in the feedback document to suppress the control.

This should probably be reported in the Sandcastle Issue Tracker if you find it to be a hassle.


I cannot see how to add a root item under which the namespaces will sit and associated summary information to that node; similarly, I do not see how to add summary (and or other) text to the namespaces themselves.

Namespaces are always listed under a root Namespaces node as of the DocProject 1.9.0 RC. Are you using the latest version?

You can edit external XML documentation, and also project and namespace documentation, using the API Topic Management dialog. Note that in the next release, 1.10.0 RC, you can simply double-click a topic in the new Topic Explorer tool window and it will open up in a document editor, without a modal dialog. There's a preview in this blog post.


Finally, how can I ensure that when documenting a library for the compact framework that the CF icons appear in the output (as per VS2005); I have seen that the icon exists in the 'icons' folder but cannot find the correct markup to ensure they are in the output.

Is this something that works outside of DocProject? e.g., on the command-line or in SHFB?

If this is somehow a bug in DocProject then I'll try to fix it. Although, DocProject does nothing with Sandcastle's transformations, icons, styles and scripts, other than to simply import them into new DocProjects and DocSites when they are first created. Therefore, if it works on the command-line then it should work in DocProject. For issues related directly to Sandcastle's presentations and output you'll probably get a resonse if you ask in Sandcastle's discussion area.

- Dave