Adding conceptual topic to a property

Topics: Conceptual Topics
Feb 18, 2009 at 9:26 PM
I need to add a required data table to each property. How would I go about doing this? I'm assuming this would be a conceptual topic but I can't seem to add a conceptual topic to a property.
Feb 19, 2009 at 1:00 AM
Hi, 

Could you please provide more detail about what you want to accomplish?

From your initial description it sounds like you're asking how you can add a table structure that contains custom information into the XML documentation comments of an API property.  If so, the answer is to use the list element and specify type="table".  If you want to only write a table that contains particular information once and then reuse it on multiple properties, you should use the include element (the MSDN page for the include element appears to have some issues right now, so see this discussion for more information and an example: http://social.msdn.microsoft.com/forums/en-US/devdocs/thread/9425dec9-55fd-40aa-be93-e6933f802322/).

Note that the term conceptual refers to MAML topics, which is end-user documentation and therefore is not associated with any one particular API member.  XML documentation comments (code comments), however, is referred to as reference documentation and is associated with a particular API.

- Dave
Feb 19, 2009 at 5:08 PM
Since we do not want to add this information to our actual code, I was wanting to add something like the example, include, see also, syntax, remarks items in the help files but named something like "required" and a title of "Required Data Fields" that would show up for each property in the chm file.

What I have are various data fields that may or may not be required by a particular provider, so one provider may require all the fields, while another one doesn't want the SSN. I've been adding the tables to the examples under my code examples, but really wanted a separate element for it.

I hope that makes sense.
Feb 20, 2009 at 4:48 PM
Hi,

It sounds like you want to create a new conceptual topic after all.

  1. Makes sure that your DocProject or DocSite is the active project in Solution Explorer.
  2. Open Topic Explorer.  (How To Use the Topic Management Dialog, Finding Topic Exporer)
  3. Click the command button that will Insert a new conceptual topic.  This will open up the Choose a template dialog.
  4. Choose the default MAML template named, Conceptual.
  5. Fill in the File name field, without adding an extension, and click OK.

Now you can use the MAML list or table element as the content of a section if want to include a list of required properties.  Note that these elements do not have the same structure as HTML, so you'll probably want to enable IntelliSense for the MAML schema:

How to Enable IntelliSense in Conceptual Topics
http://www.codeplex.com/DocProject/Wiki/View.aspx?title=How%20To%20Enable%20IntelliSense%20in%20Conceptual%20Topics


The content of this file will not be auto-generated so if you ever add or change an API property then you'll have to manually update this topic.

Alternatively, if you would like to have the topic generated automatically, you could add a dynamic build step that reads the generated reflection.xml file and recreates the table in your topic's .aml file.  My last post in this discussion (step #16) has an example of how to read from the reflection.xml file during a help build (this file describes all of your APIs being documented), although the dynamic step in that example is inserted before the, "Apply Dynamic Topic Filters" step, but you should insert yours before the, "Create Conceptual Build Files" step.  Writing to the existing .aml file in the project's Help\Topics\ folder should be fairly straightforward if you know how to use the XmlDocument class.

- Dave
Feb 20, 2009 at 5:24 PM
Thank you. It may take me a while to figure this out as I haven't touched any XML since, oh, 1993? and only for one project in a class.
Feb 25, 2009 at 5:39 PM
Okay, I followed the instructions at the links provided, but since I didn't have time to really work with it, I deleted the conceptual topic that I'd created and tried to get Intellisense to work with, however, now I cannot build the solution and get the following error:

"Access to the path 'entries' is denied."

How do I fix this error?
Feb 25, 2009 at 6:27 PM
Hi,

Please post the build trace from the output window (only the relevent portion is fine - a few steps leading up to the error) and also look for an exception stack trace in the Application event log.

From the limited information you've provided, I can guess that if you are using a source control system then maybe one of your directories named 'entries' is being deleted by DocProject or VS (for some unknown reason) but it contains a file that is currently read-only.  It also could be that the directory contains a file that is locked (by DocProject or VS), in which case restarting VS should solve the problem.  If it's locked by the Windows indexer or by some virus software, then you may have to just wait and try again later or restart your computer.

- Dave
Feb 25, 2009 at 6:57 PM
Edited Feb 25, 2009 at 6:58 PM
I've restarted VS several times over the last several days and I turn off my laptop every evening before I leave and neither seems to make a difference. I've checked all the SVN entries files in my help project and they are all there and I have all permissions.

From output window:

Starting help build for PapyrusHelp...
Preparing target directory...

System.UnauthorizedAccessException was thrown during build preparation:

Access to the path 'entries' is denied.
 
No steps executed.

PapyrusHelp help build failed.


Here's what I found in the Application event log:

Log Name:      Application
Source:        DocProject
Date:          2/25/2009 10:29:37 AM
Event ID:      0
Task Category: None
Level:         Error
Keywords:      Classic
User:          N/A
Computer:      <removed>
Description:
Event: Build process preparation.

System.UnauthorizedAccessException: Access to the path 'entries' is denied.
   at System.IO.Directory.DeleteHelper(String fullPath, String userPath, Boolean recursive)
   at System.IO.Directory.Delete(String fullPath, String userPath, Boolean recursive)
   at DaveSexton.DocProject.VSProjectItem.Delete()
   at DaveSexton.DocProject.Engine.BuildEngine`2.CleanProjectDirectory(String path)
   at DaveSexton.DocProject.Engine.BuildEngine`2.CleanProjectSubdirectory(String relativePath)
   at DaveSexton.DocProject.Sandcastle.SandcastleBuildEngine.PrepareWorkingDirectory(Boolean fullClean)
   at DaveSexton.DocProject.Sandcastle.SandcastleBuildEngine.PrepareTargetDirectory(BuildContext context)
   at DaveSexton.DocProject.Engine.BuildEngine`2.EnsureOutputDirectoryStructure(BuildContext context)
   at DaveSexton.DocProject.Engine.BuildEngine`2.PrepareForBuild(BuildContext context)
   at DaveSexton.DocProject.Engine.BuildEngine`2.BuildInternal(BuildContext context)
Event Xml:
<Event xmlns="http://schemas.microsoft.com/win/2004/08/events/event">
  <System>
    <Provider Name="DocProject" />
    <EventID Qualifiers="0">0</EventID>
    <Level>2</Level>
    <Task>0</Task>
    <Keywords>0x80000000000000</Keywords>
    <TimeCreated SystemTime="2009-02-25T17:29:37.000Z" />
    <EventRecordID>7099</EventRecordID>
    <Channel>Application</Channel>
    <Computer>darlisar-d820.softwiseonline.com</Computer>
    <Security />
  </System>
  <EventData>
    <Data>Event: Build process preparation.

System.UnauthorizedAccessException: Access to the path 'entries' is denied.
   at System.IO.Directory.DeleteHelper(String fullPath, String userPath, Boolean recursive)
   at System.IO.Directory.Delete(String fullPath, String userPath, Boolean recursive)
   at DaveSexton.DocProject.VSProjectItem.Delete()
   at DaveSexton.DocProject.Engine.BuildEngine`2.CleanProjectDirectory(String path)
   at DaveSexton.DocProject.Engine.BuildEngine`2.CleanProjectSubdirectory(String relativePath)
   at DaveSexton.DocProject.Sandcastle.SandcastleBuildEngine.PrepareWorkingDirectory(Boolean fullClean)
   at DaveSexton.DocProject.Sandcastle.SandcastleBuildEngine.PrepareTargetDirectory(BuildContext context)
   at DaveSexton.DocProject.Engine.BuildEngine`2.EnsureOutputDirectoryStructure(BuildContext context)
   at DaveSexton.DocProject.Engine.BuildEngine`2.PrepareForBuild(BuildContext context)
   at DaveSexton.DocProject.Engine.BuildEngine`2.BuildInternal(BuildContext context)</Data>
  </EventData>
</Event>