¿Qué reglas se aplican a la carpeta de salida IntelliSenseComponent de SHFB?

Question

Noda Time tiene un issue que indica que el archivo de documentación XML que envía contiene también todos los miembros internos y privados, lo que es una pena.

Afortunadamente, Sandcastle Help File Builder tiene un componente de compilación personalizado - IntelliSenseComponent - que hace exactamente lo correcto ... en teoría. Desafortunadamente, no puedo resolver cómo hacerlo para configurarlo correctamente.

La documentación da este ejemplo:

<output includeNamespaces="false" namespacesFile="Namespaces" 
    folder="{@OutputFolder}" /> 

y estados:

El ejemplo anterior se toma del castillo de arena Ayuda archivo archivo de configuración del constructor. Cuando se utiliza con él, las etiquetas de reemplazo {@SHFBFolder} y {@OutputFolder} se utilizan para insertar la carpeta del creador del archivo de ayuda y la carpeta de salida del proyecto en las rutas de archivos. Estos se reemplazan en tiempo de compilación con los valores apropiados. Si utiliza el componente en sus propios scripts de compilación, reemplace las etiquetas con una ruta relativa o absoluta al conjunto de componentes y la carpeta de salida, respectivamente.

Bueno, am usando SHFB, por lo que yo esperaría que para trabajar. Sin embargo, no puedo obtener nada que no sea una ruta de acceso absoluta al trabajo. He intentado:

folder="." 
folder="{@OutputFolder}" 
folder="{@OutputFolder}XYZZY" 
folder="{@OutputFolder}\XYZZY" 
folder="{@OutputFolder}/XYZZY" 
folder="{@OutputFolder}/XYZZY/" 

(. Sólo estoy usando XYZZY como algo que es fácil de buscar)

Mirando el source code, yo esperaba que podría utilizar una variable de entorno, pero esto no funcionó:

folder="%CD%\XYZZY" 

aunque esto hizo ...

folder="%USERPROFILE%\XYZZY" 

esto funciona:

folder="c:\users\jon\test\xyzzy" 

... pero realmente no quiero un nombre de ruta absoluto allí.

La documentación sugiere que todo esto debería ser realmente fácil ... ¿Qué me estoy perdiendo?

Versiones implicados:

• SHFB: 1.9.3.0
• castillo de arena: 2.6.10621.1

Answer 1

Mis experimentos mostraron que de SHFB IntelliSenseComponent hizo tratar {@OutputFolder} correctamente, pero hay un matiz.

Si el atributo folder especifica en

<output includeNamespaces="false" namespacesFile="Namespaces" 
     folder="..." /> 

puntos a una carpeta dentroOutputPath la carpeta de un proyecto (.\docs\api en su caso), entonces proceso de construcción de SHFB crea la carpeta, pero luego lo elimina antes de generar contenidos del sitio web :

Last step completed in 00:00:34.5875 
------------------------------- 
Combining conceptual and API intermediate TOC files... 

Clearing any prior web output 
    Last step completed in 00:00:00.2360 
------------------------------- 
Extracting HTML info for HTML Help 1 and/or website... 

El problema es que el valor predeterminado de {@OutputFolder} es exactamente el mismo que el valor $(OutputPath), por lo tanto, si pone algo como {@OutputFolder}\foo en el atributo folder, nunca verá foo después de que la construcción haya finalizado.

La solución es simple: especificar una carpeta que se encuentra fuera de de la carpeta de salida del proyecto, así:

<output includeNamespaces="false" namespacesFile="Namespaces" 
     folder="{@OutputFolder}\..\distilledApi" /> 
<!--       ^^  --> 

Espero que esto ayude.