.net - traduccion - ¿Qué reglas se aplican a la carpeta de salida de IntelliSenseComponent de SHFB?

sandcastle visual studio 2017

Question

Noda Time tiene un issue contra de que el archivo de documentación XML que incluye contiene 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 averiguar cómo configurarlo correctamente.

La documentación da este ejemplo:

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

y estados:

El ejemplo dado anteriormente se toma del archivo de configuración del Generador de archivos de ayuda de Sandcastle. Cuando se usa con él, las etiquetas de reemplazo {@SHFBFolder} y {@OutputFolder} se usan para insertar la carpeta del creador del archivo de ayuda y la carpeta de salida del proyecto en las rutas del archivo. Estos son reemplazados en el momento de la construcción con los valores apropiados. Si usa el componente en sus propios scripts de compilación, reemplace las etiquetas con una ruta relativa o absoluta al ensamblaje del componente y la carpeta de salida, respectivamente.

Bueno, estoy usando SHFB, así que espero que funcione. Sin embargo, no puedo conseguir nada más que un camino absoluto para trabajar. He intentado:

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

(Solo uso XYZZY como algo que es fácil de buscar).

Mirando el código fuente , esperaba poder usar 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 involucradas:

• SHFB: 1.9.3.0
• Castillo de arena: 2.6.10621.1

Answer 1

Mis experimentos mostraron que IntelliSenseComponent de SHFB trató a {@OutputFolder} correctamente, pero hay un matiz.

Si el atributo de folder especificado en

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

apunta a una carpeta dentro de la carpeta OutputPath un proyecto ( ./docs/api en su caso), luego el proceso de construcción de SHFB crea la carpeta, pero luego la elimina antes de generar el contenido 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 de $(OutputPath) , por lo tanto, si coloca algo como {@OutputFolder}/foo en el atributo de folder , nunca verá foo después. la construcción ha terminado.

La solución es simple: especifique una carpeta que se encuentre fuera de la carpeta de salida de su proyecto, como esta:

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

Espero que esto ayude.