Quick Start: Creating a DocSite

C# DocSite VB.NET DocSite

DocSite ASP.NET Web Application Example Enlarge
Figure 1: DocSite ASP.NET Web Application Example

Introduction

To get started building a new DocSite, the following steps may be taken after the successful installation of DocProject, Sandcastle and ASP.NET 2.0 AJAX Extensions 1.0.

Note: A separate AJAX installation is only required for Visual Studio 2005, not 2008.

See the Latest Release Notes for more information and additional requirements.

For more information about DocSites, see DocSite Templates.
For more information about DocProjects in general, see DocProject Templates.

Instructions

Follow these steps to create a new DocSite in an existing solution:
  1. Open a solution with at least one project for which you would like to create a documentation website.
    1. Any Visual C#, Visual Basic, Visual J# or Managed Visual C++ project is supported, including Web Application projects; however, Web Site projects must be added as external sources. See How To Build Help For a Web Site Project for more information.
  2. Add a new project to the solution and select one of the DocSite templates.
    1. The templates can be located by selecting the language of your choice from the Project Types list (e.g., Visual C# or Visual Basic).
    2. Expand the language node and select the DocProject subcategory.
    3. Look under the My Templates section in the Templates area.
    4. For this tutorial, choose a DocSite template.
    5. Note: If you receive an error that the project type is not supported then you must update Visual Studio 2005 for use with Web Application projects. For more information, see How To Configure Visual Studio 2005 For DocProject.
  3. When a new DocProject or DocSite is created, the New Project Wizard is launched automatically to help you configure your project. For more information, see Configuring Projects with the New Project Wizard.
    1. In the first couple of steps you may choose any build engine and Sandcastle presentation style that you'd like.
      1. For information about the Sandcastle/Deployment engine, see Sandcastle Deployment Plugin.
    2. In the step that offers compiled help you may choose Help 1.x, Help 2.x, both or neither of them. You can change this setting at a later time in the DocProject Properties window or the DocProject External UI. For more information, see How To Configure DocProject.
    3. Make sure that you select one or more projects in the last step of the wizard before clicking Finish.
      1. If you clicked Finish without selecting any source projects then you can add them at a later time as project references; e.g., right-mouse click the DocSite project in Solution Explorer, select Add Reference... and then choose your DocSite's sources from the Projects tab.
      2. Note: If the projects that you'd like to document do not appear in the list then DocProject cannot use them as project references; however, if they produce managed assemblies then you can reference the assemblies as external sources later on using the External sources project option.
  4. Optionally, configure additional project options before building using the DocProject Properties window:
    1. Right-mouse click the project node in Solution Explorer and select DocProject Properties.
    2. Use the Build > External sources project option now if you'd like to reference folders, individual assemblies, or raw reflection XML files as sources for auto-generated reference documentation.
    3. Note: The DocProject Properties window is only available in Visual Studio Standard edition and higher. Visual Studio Express users can configure the project using the DocProject External UI.
    4. See How To Configure DocProject for more information.
  5. Press Ctrl+F5 to build and view the DocSite or press F5 alone to build and attach to the website in debug mode.

Further Development

You can work on the DocSite as you would work on a normal Web Application project, because that's exactly what it is. Feel free to modify the DocSite.Master and DocSite.css files, for example.

The only DocSite files that you shouldn't modify are the DocSiteContents.xml and DocSiteIndex.xml files since they are recreated every time a Partial or Full build is executed. If you do decide to update these files, be sure to save a copy of your changes elsewhere so you can merge them with the regenerated versions the next time you perform a Partial or Full build. DocSites that use the Sandcastle build engine contain other project items that should only be modified in certain situations. For more information, see the Sandcastle section below.

For more information on Partial and Full builds, see Build Process.

Logo
You can replace the default Logo.jpg file with your company's logo if you'd like without any other required modifications. The default image is 51x51 pixels in size. (The odd number, 51, allows for parts of the logo to be properly centered within itself).

Company Name and Copyright
The company name and copyright information found in the header and footer are taken from the project's AssemblyInfo file, found in the Properties directory. To edit this file using the project's properties dialog, double-click the Properties folder in Solution Explorer, select the Application tab and click the Assembly Information... button.

Hackable URLs

Hackable URLs are created by browsing to the root url and adding a query string starting with ?topic=. Append each topic name to ?topic= in parent-child order, from left to right, separated by slashes, and then finally the destination topic name that will be displayed, at the end.

Here is an example of a valid url that points to a topic named, Form1 Constructor under a topic named, Form1, at the help system's root, Namespaces:

~/Default.aspx?topic=Namespaces/Form1/Form1+Constructor

Notes:
  • The tilde is an optional token that represents the application's root directory. This is useful for nesting applications.
  • The symbol is a url-escape character that represents a single space. %20 is an alternative that may be used instead of the symbol.
  • Leading and trailing spaces are valid in topic names, so make sure they are added to the urls using the + or %20 escapes.

Sandcastle's Files

If you have decided to use the Sandcastle build engine (the only engine that ships with DocProject), then please note that any changes you make to the Html Help Workshop files will be lost the next time a Full build occurs. The same goes for any of the files in the Html and Html2 directories as they are all generated by Sandcastle during a Full build. However, you can freely update any of the files in the Icons, Scripts, Styles and Presentation directories since they are only copied into the DocSite by the wizard when it's first created and will not be affected by building the project. In fact, the files in these directories are used to build the compiled help, so you can update them to control Sandcastle's output as you see fit.

For more information, see Build Process, Sandcastle Project Items.

Transforms and Content Folders
Files in the Transforms and Content folders, under the Presentation folder, can be updated. They are not replaced when the project is built. Use these files to control the presentation of Sandcastle's HTML output.

Last edited Jun 11, 2008 at 5:52 AM by davedev, version 19

Comments

No comments yet.