Sandcastle과 DocProject를 이용해 ASP.NET 웹사이트 코드 문서 만들기 ASP.NET

sandcastle1.png
ASP.NET 웹사이트 프로젝트의 XML 주석들로 위처럼 문서화하는 것이 목적이다.

테스트 환경 : Windows 7 RC x64, Visual Studio 2008 Professional, ASP.NET 3.5 Web site project

1. sandcastle.msi를 설치한다. (http://www.codeplex.com/Sandcastle, 여기서는 May 2008)
amd64 시스템에서는 path에 다음을 추가한다.
;%ProgramFiles(x86)%\HTML Help Workshop;%ProgramFiles(x86)%\Common Files\Microsoft Shared\Help 2.0 Compiler
(참고 : http://sandcastle.codeplex.com/Wiki/View.aspx?title=How%20to%3a%20Install%20Sandcastle&referringTitle=Home)

2. DotProject for Sandcastle 설치 (http://docproject.codeplex.com/, 여기서는 1.11.0)

3. Visual Studio® 2008 Web Deployment Projects - RTW 설치
(http://www.microsoft.com/downloads/details.aspx?FamilyId=0AA30AE8-C73B-4BDD-BB1B-FE697256C459&displaylang=en)

4. Visual Studio가 켜져 있었으면 재시작, 문서화할 프로젝트가 포함된 솔루션을 연다.

5. 웹 사이트를 선택하고 컨텍스트 메뉴에서 Add Web Deployment Project

sandcastle2.png

6. Documenting Web Projects 다운로드 (http://www.codeplex.com/SandcastleStyles, 여기서는 1.1.0.0),
압축을 푼 뒤 Web/WebCodeProviders/Bin/Release의 EWSoftware.CodeDom.dll을 복사해서 프로젝트의 Bin에 넣거나,
gacutil을 써서 전역 라이브러리로 등록한다.

sandcastle4.png

7. 사이트에 web.config 파일이 없으면 만든다. web.config의 <system.codedom><compilers>를 찾아 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>

(vb도 마찬가지)
식으로 속성을 추가 혹은 대체한 후 프로젝트를 빌드, XML 파일이 해당 경로에 생성된 것을 본다.

sandcastle3.png  

팁 : "Program Files"나 "Visual Studio 2008" 처럼 이름에 띄어쓰기가 들어간 경우는 다음과 같이 해야 에러가 없다.
        compilerOptions='/docpath:"C:\Users\setzer\Documents\Visual Studio 2008\Projects\project1\docs"'

8. HTML Help Workshop 설치 (htmlhelp.exe), 필자의 경우 이것을 설치하지 않으면 1.x 파일 빌드시 에러가 났고,
설치시에는 설치중 '이미 최신버전이 설치되어 있음' 이라는 에러가 나왔음에도 불구 작업 후에는 정상 동작했다.
http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc

9. 솔루션에 DocProject 프로젝트 추가 -> Sandcastle -> Visual Studio 2005 -> (공백) -> Help 1.x(항상 활성회됨) 혹은
Help 2.x (VS SDK 설치시만 활성화됨) -> 완료

10. 생성된 DocProject의 컨텍스트 메뉴에서 DocProject properties를 실행, Build | External sources의 ...을 눌러 선택창을 연다.

11. Deploy 프로젝트 폴더에서 DLL 파일 선택, 원본 폴더에서 App_Code.xml XML 파일 선택 후 확인

12. DocProejct 프로젝트 빌드

모든 작업을 마치면 chm 파일이 생성된다.

sandcastle6.png   

(3~12 :
"How to Build Help For a Web Site Project 참고함
http://docproject.codeplex.com/Wiki/View.aspx?title=How%20To%20Build%20Help%20For%20a%20Web%20Site%20Project&referringTitle=Home)
(7:
"Documenting Web Projects" 참고함
http://www.ewoodruff.us/shfbdocs/html/94c7f744-9b90-4254-93ab-9b15f47d9f42.htm)


추가 : HxS 파일이 필요한 경우 VS2008 SDK를 설치해야 한다.

1. Visual Studio 2008 SDK Version 1.1 다운로드, 설치
http://www.microsoft.com/downloads/details.aspx?familyid=59EC6EC3-4273-48A3-BA25-DC925A45584D&displaylang=en

2. 설치를 마치면 한글판 VS의 경우 갑자기 영문판이 되면서 모든 패키지가 Disabled 되는 상황이 발생할 때가 있다.
이 때는 c:\program files (x86)\microsoft visual studio 9.0\common7\ide 에서 devenv /LCID 1042 하여 한글판으로 다시 실행해주면
이후로는 원래대로 한글판으로 잘 실행 된다.
Tag :
, , , ,

Leave Comments