Quy tắc nào được áp dụng cho thư mục đầu ra của IntelliSenseComponent của SHFB?

Question

Noda Time có một số issue chống lại nó rằng tệp tài liệu XML mà nó chứa tất cả các thành viên nội bộ và tư nhân quá - đó là một sự xấu hổ.

May mắn thay, Sandcastle Help File Builder có thành phần xây dựng tùy chỉnh - IntelliSenseComponent - thực hiện chính xác điều đúng ... về mặt lý thuyết. Thật không may, tôi không thể tìm ra cách để cấu hình nó đúng cách.

Các tài liệu cung cấp cho ví dụ này:

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

và khẳng định:

Ví dụ đưa ra ở trên được lấy từ Sandcastle Trợ giúp tập tin tập tin cấu hình xe cộ và máy. Khi được sử dụng, thẻ thay thế {@SHFBFolder} và {@OutputFolder} được sử dụng để chèn thư mục của trình tạo tệp trợ giúp và thư mục đầu ra của dự án vào đường dẫn tệp. Chúng được thay thế tại thời gian xây dựng với các giá trị thích hợp. Nếu sử dụng thành phần trong các kịch bản xây dựng của riêng bạn, hãy thay thế các thẻ có đường dẫn tương đối hoặc tuyệt đối thành thư mục thành phần và thư mục đầu ra tương ứng.

Vâng, tôi am sử dụng SHFB, vì vậy tôi hy vọng rằng sẽ hoạt động. Tuy nhiên, tôi không thể nhận được bất kỳ điều gì ngoài đường dẫn tuyệt đối để hoạt động. Tôi đã thử:

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

(. Tôi chỉ sử dụng xyzzy như cái gì đó là dễ dàng để tìm kiếm)

Nhìn vào source code, tôi hy vọng rằng tôi có thể sử dụng một biến môi trường, nhưng điều này không làm việc:

folder="%CD%\XYZZY" 

mặc dù điều này đã làm ...

folder="%USERPROFILE%\XYZZY" 

này hoạt động:

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

... nhưng tôi thực sự không muốn có tên đường dẫn tuyệt đối ở đó.

Tài liệu gợi ý rằng tất cả điều này nên thực sự dễ dàng ... tôi đang thiếu gì?

phiên bản có liên quan:

• SHFB: 1.9.3.0
• Sandcastle: 2.6.10621.1

Answer 1

thí nghiệm của tôi cho thấy SHFB của IntelliSenseComponent đã điều trị {@OutputFolder} một cách chính xác, nhưng có một sắc thái.

Nếu thuộc tính folder quy định tại

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

điểm vào một thư mục bênOutputPath thư mục của dự án (.\docs\api trong trường hợp của bạn) sau đó quá trình xây dựng SHFB của tạo thư mục, nhưng sau đó xóa nó trước khi tạo nội dung website :

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... 

Vấn đề là giá trị mặc định của {@OutputFolder} là chính xác giống như giá trị của $(OutputPath), do đó nếu bạn đặt một cái gì đó như {@OutputFolder}\foo trong thuộc tính folder thì bạn sẽ không bao giờ thấy foo sau khi xây dựng xong.

Các giải pháp rất đơn giản: chỉ định một thư mục đó nằm bên ngoài của thư mục đầu ra của dự án của bạn, như thế này:

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

Hope this helps.