Quick Start: Creating a DocSite
DocSite ASP.NET Web Application Example
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
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
Follow these steps to create a new DocSite
in an existing solution:
- Open a solution with at least one project for which you would like to create a documentation website.
- 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.
- Add a new project to the solution and select one of the DocSite templates.
- The templates can be located by selecting the language of your choice from the Project Types list (e.g., Visual C# or Visual Basic).
- Expand the language node and select the DocProject subcategory.
- Look under the My Templates section in the Templates area.
- For this tutorial, choose a DocSite template.
- 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.
- 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.
- In the first couple of steps you may choose any build engine and Sandcastle presentation style that you'd like.
- For information about the Sandcastle/Deployment engine, see Sandcastle Deployment Plugin.
- 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.
- Make sure that you select one or more projects in the last step of the wizard before clicking Finish.
- 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.
- 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.
- Optionally, configure additional project options before building using the DocProject Properties window:
- Right-mouse click the project node in Solution Explorer and select DocProject Properties.
- 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.
- 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.
- See How To Configure DocProject for more information.
- Press Ctrl+F5 to build and view the DocSite or press F5 alone to build and attach to the website in debug mode.
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
files, for example.
The only DocSite
files that you shouldn't modify are the DocSiteContents.xml
files since they are recreated every time a Partial
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
that use the Sandcastle build engine contain other project items that should only be modified in certain situations. For more information, see the Sandcastle
For more information on Partial
builds, see Build Process
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...
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.
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
directories as they are all generated by Sandcastle
during a Full
build. However, you can freely update any of the files in the Icons
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
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.