Solución 5 - "SandCastle"

Automatiza el proceso de documentación.

Permite crear .chm y .html de la documentación que hay incrustada en el código de proyectos, de estética muy similar al MSDN.

Documentación general: http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/b772e00e-1705-4062-adb6-774826ce6700.htm

Instalar Sandcastle

http://sandcastle.codeplex.com/releases/view/47665

Instalar el “Sandcastle Help File Builder”

http://shfb.codeplex.com/releases/view/40105

Documentación sobre la instalación: http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/b772e00e-1705-4062-adb6-774826ce6700.htm

 Para escritorio: Añadir el proyecto/solución.

 Para web y webservices: Es necesario publicar como “updatable” y añadir el web.config una nueva sección (http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/b772e00e-1705-4062-adb6-774826ce6700.htm).  Hay que añadir una dll en el Bin: EWSoftware.CodeDom.dll .

<configuration>
  <system.codedom>
    <compilers>
      <!-- For C# -->
      <compiler language="c#;cs;csharp" extension=".cs"
        compilerOptions="/docpath:C:\Publish\Docs"
        type="EWSoftware.CodeDom.CSharpCodeProviderWithDocs,
              EWSoftware.CodeDom, Version=1.1.0.0, Culture=neutral,
              PublicKeyToken=d633d7d5b41cbb65">
        <!-- NOTE: Change value to "v3.5" for .NET 3.5 projects -->
        <providerOption name="CompilerVersion" value="v2.0"/>
      </compiler>
 
      <!-- For VB.NET -->
      <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb"
        compilerOptions="/docpath:C:\Publish\Docs"
        type="EWSoftware.CodeDom.VBCodeProviderWithDocs,
              EWSoftware.CodeDom, Version=1.1.0.0, Culture=neutral,
              PublicKeyToken=d633d7d5b41cbb65">
        <!-- NOTE: Change value to "v3.5" for .NET 3.5 projects -->
        <providerOption name="CompilerVersion" value="v2.0"/>
      </compiler>
    </compilers>
  </system.codedom>
</configuration>

En esta sección indicar donde se van a guardar los xml generados del proyecto (/docpath). Luego en el SHFB añadir las dll’s necesarias, la solución/projecto y los xml generados.

Ejemplo. En el caso de querer documentar los servicios de un webservice se tendría que añadir al SHFB:  App_code.xml, App_code.dll y WService.sln

Posibles problemas detectados:

-          Necesidad de cambiar variables globales DXROOT y PATH: http://www.ewoodruff.us/shfbdocs/html/378d6894-02b8-4ee9-9c50-58f278490ed8.htm. Solo ocurre cuando has instalado incorrectamente versiones incompatibles de Sandcastle y Sandcastle Help File Builder.